convo-cli 0.1.0__py3-none-any.whl

convo/llm/client.py

@@ -0,0 +1,207 @@
+"""Generate evidence-grounded answers through a connected ChatGPT account."""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+from openai import BadRequestError
+
+from convo.core.contracts import (
+    Answer,
+    ChatModel,
+    GenerationSelection,
+    Hit,
+    Message,
+    ReasoningEffort,
+)
+from convo.core.exceptions import BackendNotConnected
+from convo.llm.auth import RESOURCE, ChatGPTAuth
+from convo.llm.models import parse_model_catalog
+from convo.llm.streaming import complete_chatgpt
+from convo.prompts.answers import INSTRUCTIONS, bounded_hits, make_input
+from convo.prompts.schema import insufficient_answer, parse_answer
+
+MODEL_LIST_URL = f"{RESOURCE}/models"
+
+
+class ChatGPTProvider:
+    """OpenAI generation through the user's connected ChatGPT account."""
+
+    def __init__(self, auth: ChatGPTAuth) -> None:
+        self.auth = auth
+        self._models: tuple[ChatModel, ...] = ()
+        self._catalog_at = 0.0
+        self._catalog_account: tuple[str, str] | None = None
+
+    def reset_catalog(self) -> None:
+        self._models = ()
+        self._catalog_at = 0.0
+        self._catalog_account = None
+
+    def generation_selection(self) -> GenerationSelection:
+        profile = self.auth.account_profile()
+        if profile is None:
+            return GenerationSelection()
+        if profile.selected_model is None:
+            return GenerationSelection(connected=True)
+        model = next((item for item in self._models if item.id == profile.selected_model), None)
+        if model is None:
+            model = ChatModel(
+                profile.selected_model, profile.selected_model_name or profile.selected_model
+            )
+        return GenerationSelection(model, profile.selected_reasoning_effort, connected=True)
+
+    async def list_models(self) -> tuple[ChatModel, ...]:
+        await self._refresh_catalog(await self.auth.access_token())
+        return self._models
+
+    async def _refresh_catalog(self, access_token: str) -> None:
+        models = await list_account_models(access_token)
+        if not models:
+            raise BackendNotConnected("This ChatGPT account has no models available for Convo.")
+        profile = self.auth.account_profile()
+        if profile is None:
+            raise BackendNotConnected("Connect your ChatGPT account with /login")
+        model = next((item for item in models if item.id == profile.selected_model), models[0])
+        effort = (
+            profile.selected_reasoning_effort
+            if model.id == profile.selected_model
+            and profile.selected_reasoning_effort in model.reasoning_efforts
+            else None
+        )
+        if (
+            profile.selected_model,
+            profile.selected_model_name,
+            profile.selected_reasoning_effort,
+        ) != (model.id, model.name, effort):
+            self.auth.save_generation_preferences(model.id, model.name, effort)
+        self._models = models
+        self._catalog_account = (profile.client_id, profile.subject)
+        self._catalog_at = time.monotonic()
+
+    async def _ensure_catalog(self, access_token: str | None = None) -> None:
+        profile = self.auth.account_profile()
+        account = (profile.client_id, profile.subject) if profile else None
+        if (
+            not self._models
+            or account != self._catalog_account
+            or time.monotonic() - self._catalog_at > 300
+        ):
+            await self._refresh_catalog(access_token or await self.auth.access_token())
+
+    async def select_model(self, model_id: str) -> GenerationSelection:
+        await self._ensure_catalog()
+        model = next((item for item in self._models if item.id == model_id), None)
+        if model is None:
+            raise ValueError("That model is no longer available. Run /models to refresh the list.")
+        current = self.generation_selection()
+        effort = (
+            current.reasoning_effort
+            if current.reasoning_effort in model.reasoning_efforts
+            else None
+        )
+        self.auth.save_generation_preferences(model.id, model.name, effort)
+        return GenerationSelection(model, effort, connected=True)
+
+    async def cycle_reasoning(self) -> GenerationSelection:
+        await self._ensure_catalog()
+        current = self.generation_selection()
+        model = current.model
+        if model is None:
+            raise BackendNotConnected("Choose a ChatGPT model with /models first")
+        choices = (None, *model.reasoning_efforts)
+        index = (
+            choices.index(current.reasoning_effort) if current.reasoning_effort in choices else 0
+        )
+        effort = choices[(index + 1) % len(choices)]
+        self.auth.save_generation_preferences(model.id, model.name, effort)
+        return GenerationSelection(model, effort, connected=True)
+
+    async def select_reasoning(self, effort: ReasoningEffort | None) -> GenerationSelection:
+        await self._ensure_catalog()
+        model = self.generation_selection().model
+        if model is None:
+            raise BackendNotConnected("Choose a ChatGPT model with /models first")
+        if effort is not None and effort not in model.reasoning_efforts:
+            supported = ", ".join(("auto", *model.reasoning_efforts))
+            raise ValueError(f"{model.name} supports these thinking levels: {supported}.")
+        self.auth.save_generation_preferences(model.id, model.name, effort)
+        return GenerationSelection(model, effort, connected=True)
+
+    async def answer(
+        self,
+        filename: str,
+        question: str,
+        history: tuple[Message, ...],
+        hits: list[Hit],
+    ) -> Answer:
+        excerpts = bounded_hits(hits)
+        if not excerpts:
+            return insufficient_answer()
+        access_token = await self.auth.access_token()
+        await self._ensure_catalog(access_token)
+        selection = self.generation_selection()
+        if selection.model is None:
+            raise BackendNotConnected("Choose a ChatGPT model with /models first")
+        input_items = make_input(filename, question, history, excerpts)
+        for attempt in range(2):
+            try:
+                raw = await complete_chatgpt(
+                    access_token=access_token,
+                    model=selection.model.id,
+                    instructions=INSTRUCTIONS,
+                    input_items=input_items,
+                    reasoning_effort=selection.reasoning_effort,
+                    structured=True,
+                )
+            except BadRequestError as error:
+                raise BackendNotConnected(
+                    "The selected model could not accept the structured-answer request. "
+                    "Choose another model with /models and retry."
+                ) from error
+            try:
+                return parse_answer(raw, filename, excerpts)
+            except ValueError:
+                if attempt:
+                    raise BackendNotConnected(
+                        "ChatGPT could not produce a valid answer with supporting quotations. "
+                        "Try a more specific question; no incomplete answer was saved."
+                    ) from None
+                input_items.extend(
+                    [
+                        {"role": "assistant", "content": raw[:30_000]},
+                        {
+                            "role": "user",
+                            "content": "Your response failed evidence validation. Return the "
+                            "required schema with a supporting citation for each answer section. Use only "
+                            "the current source IDs and exact quotes copied from their excerpts. No inline "
+                            "citation markers in text. If unsupported, use insufficient_evidence.",
+                        },
+                    ]
+                )
+        raise RuntimeError("No validated answer")
+
+
+async def list_account_models(access_token: str) -> tuple[ChatModel, ...]:
+    """Fetch the account's displayable model catalog in the server's order."""
+    try:
+        async with httpx.AsyncClient(timeout=20) as client:
+            response = await client.get(
+                MODEL_LIST_URL,
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+            response.raise_for_status()
+            return parse_model_catalog(response.json())
+    except httpx.HTTPStatusError as error:
+        if error.response.status_code in (401, 403):
+            raise BackendNotConnected(
+                "ChatGPT model access was denied. Reconnect with /login."
+            ) from error
+        raise BackendNotConnected(
+            "Could not load ChatGPT models. Retry /models shortly."
+        ) from error
+    except httpx.HTTPError as error:
+        raise BackendNotConnected(
+            "Could not reach ChatGPT. Check your connection and retry /models."
+        ) from error

convo/llm/credentials.py

@@ -0,0 +1,192 @@
+"""Secure token storage and owner-only account metadata for local sign-in."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Protocol
+
+from convo.core.contracts import REASONING_EFFORTS, ReasoningEffort
+
+
+class CredentialStore(Protocol):
+    """Small seam around secure local token storage."""
+
+    def save(self, key: str, value: str) -> None: ...
+
+    def load(self, key: str) -> str | None: ...
+
+    def delete(self, key: str) -> None: ...
+
+
+class KeyringCredentialStore:
+    """Store OAuth secrets in the operating system's credential manager."""
+
+    service_name = "convo"
+
+    def save(self, key: str, value: str) -> None:
+        import keyring
+
+        keyring.set_password(self.service_name, key, value)
+
+    def load(self, key: str) -> str | None:
+        import keyring
+
+        return keyring.get_password(self.service_name, key)
+
+    def delete(self, key: str) -> None:
+        import keyring
+        from keyring.errors import PasswordDeleteError
+
+        try:
+            keyring.delete_password(self.service_name, key)
+        except PasswordDeleteError:
+            pass
+
+
+@dataclass(frozen=True)
+class AccountProfile:
+    """Non-secret metadata for the one ChatGPT account connected to this CLI."""
+
+    client_id: str
+    subject: str
+    email: str | None
+    name: str | None
+    issuer: str
+    scopes: tuple[str, ...]
+    expires_at: float
+    selected_model: str | None = None
+    selected_model_name: str | None = None
+    selected_reasoning_effort: ReasoningEffort | None = None
+
+    @classmethod
+    def from_dict(cls, value: dict[str, object]) -> AccountProfile:
+        scopes = value.get("scopes")
+        if not isinstance(scopes, list) or not all(isinstance(scope, str) for scope in scopes):
+            raise ValueError("Invalid scopes in saved ChatGPT profile")
+        client_id = value.get("client_id")
+        subject = value.get("subject")
+        issuer = value.get("issuer")
+        expires_at = value.get("expires_at")
+        email = value.get("email")
+        name = value.get("name")
+        selected_model = value.get("selected_model")
+        selected_model_name = value.get("selected_model_name")
+        selected_effort = value.get("selected_reasoning_effort")
+        if not isinstance(client_id, str) or not client_id:
+            raise ValueError("Invalid identity in saved ChatGPT profile")
+        if not isinstance(subject, str) or not subject:
+            raise ValueError("Invalid identity in saved ChatGPT profile")
+        if not isinstance(issuer, str) or not issuer:
+            raise ValueError("Invalid identity in saved ChatGPT profile")
+        if not isinstance(expires_at, (float, int)):
+            raise ValueError("Invalid expiry in saved ChatGPT profile")
+        if email is not None and not isinstance(email, str):
+            raise ValueError("Invalid email in saved ChatGPT profile")
+        if name is not None and not isinstance(name, str):
+            raise ValueError("Invalid name in saved ChatGPT profile")
+        if selected_model is not None and not isinstance(selected_model, str):
+            raise ValueError("Invalid selected model in saved ChatGPT profile")
+        return cls(
+            client_id=client_id,
+            subject=subject,
+            email=email,
+            name=name,
+            issuer=issuer,
+            scopes=tuple(scopes),
+            expires_at=float(expires_at),
+            selected_model=selected_model,
+            selected_model_name=selected_model_name
+            if isinstance(selected_model_name, str)
+            else None,
+            selected_reasoning_effort=(
+                selected_effort
+                if isinstance(selected_effort, str) and selected_effort in REASONING_EFFORTS
+                else None
+            ),
+        )
+
+
+def default_config_dir() -> Path:
+    """Return the per-user config directory; allow a test/developer override."""
+    override = os.environ.get("CONVO_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "convo"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "convo"
+    return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "convo"
+
+
+class AccountProfileStore:
+    """Persist a stable host ID and non-secret account details outside the repo."""
+
+    def __init__(self, directory: Path | None = None) -> None:
+        self.directory = (directory or default_config_dir()).expanduser()
+        self.profile_path = self.directory / "chatgpt-profile.json"
+        self.host_id_path = self.directory / "host-id"
+
+    def _ensure_private_directory(self) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if os.name != "nt":
+            self.directory.chmod(0o700)
+
+    def host_id(self) -> str:
+        self._ensure_private_directory()
+        try:
+            value = self.host_id_path.read_text(encoding="utf-8").strip()
+        except FileNotFoundError:
+            value = ""
+        if value.startswith("urn:uuid:") and len(value) == len("urn:uuid:") + 36:
+            return value
+
+        from uuid import uuid4
+
+        value = f"urn:uuid:{uuid4()}"
+        self._write_private(self.host_id_path, value.encode("utf-8"))
+        return value
+
+    def load(self) -> AccountProfile | None:
+        try:
+            raw = self.profile_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return None
+        try:
+            value = json.loads(raw)
+            if not isinstance(value, dict):
+                raise ValueError("Saved ChatGPT profile must be a JSON object")
+            return AccountProfile.from_dict(value)
+        except (json.JSONDecodeError, ValueError) as error:
+            raise ValueError("Saved ChatGPT profile is invalid; sign in again") from error
+
+    def save(self, profile: AccountProfile) -> None:
+        self._ensure_private_directory()
+        content = json.dumps(asdict(profile), indent=2, sort_keys=True).encode("utf-8")
+        self._write_private(self.profile_path, content)
+
+    @staticmethod
+    def _write_private(path: Path, content: bytes) -> None:
+        """Atomically replace a file and keep it owner-readable on Unix."""
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        temporary_path = Path(temporary_name)
+        try:
+            if os.name != "nt":
+                os.fchmod(descriptor, 0o600)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(content)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary_path, path)
+            if os.name != "nt":
+                path.chmod(0o600)
+        finally:
+            try:
+                temporary_path.unlink()
+            except FileNotFoundError:
+                pass

convo/llm/models.py

@@ -0,0 +1,71 @@
+"""Normalize account catalogs and limit reasoning controls to known capabilities."""
+
+import re
+
+from convo.core.contracts import REASONING_EFFORTS, ChatModel, ReasoningEffort
+
+# A conservative subset documented for these standard models. Catalog-provided
+# capabilities take precedence; unfamiliar models keep the server's default.
+_STANDARD_REASONING_MODELS = (
+    "gpt-5.5",
+    "gpt-5.6",
+    "gpt-6-astra",
+    "gpt-6-sol",
+    "gpt-6.1-sol",
+    "gpt-6-luna",
+)
+
+
+def reasoning_effort(value: object) -> ReasoningEffort | None:
+    if isinstance(value, str) and value in REASONING_EFFORTS:
+        return value
+    return None
+
+
+def parse_model_catalog(payload: object) -> tuple[ChatModel, ...]:
+    if not isinstance(payload, dict) or not isinstance(payload.get("models"), list):
+        raise RuntimeError("ChatGPT returned an invalid model catalog")
+    models: list[ChatModel] = []
+    seen: set[str] = set()
+    for item in payload["models"]:
+        if not isinstance(item, dict) or item.get("visibility") != "list":
+            continue
+        slug = item.get("slug")
+        if not isinstance(slug, str) or not slug or slug in seen:
+            continue
+        seen.add(slug)
+        display_name = item.get("display_name")
+        capabilities = item.get(
+            "supported_reasoning_levels", item.get("supported_reasoning_efforts")
+        )
+        if isinstance(capabilities, list):
+            efforts = {
+                effort
+                for entry in capabilities
+                if (
+                    effort := reasoning_effort(
+                        entry.get("effort") if isinstance(entry, dict) else entry
+                    )
+                )
+                is not None
+            }
+            supported = tuple(effort for effort in REASONING_EFFORTS if effort in efforts)
+        elif any(
+            re.fullmatch(re.escape(model) + r"(?:-\d{4}-\d{2}-\d{2})?", slug)
+            for model in _STANDARD_REASONING_MODELS
+        ):
+            supported = ("low", "medium", "high")
+        else:
+            supported = ()
+        default = reasoning_effort(
+            item.get("default_reasoning_level", item.get("default_reasoning_effort"))
+        )
+        models.append(
+            ChatModel(
+                id=slug,
+                name=display_name if isinstance(display_name, str) and display_name else slug,
+                reasoning_efforts=supported,
+                default_reasoning_effort=default if default in supported else None,
+            )
+        )
+    return tuple(models)

convo/llm/streaming.py

@@ -0,0 +1,62 @@
+"""Collect ChatGPT's required streamed Responses API events into one answer."""
+
+from typing import cast
+
+from openai import AsyncOpenAI, omit
+from openai.types.responses import ResponseFormatTextJSONSchemaConfigParam, ResponseInputParam
+
+from convo.core.contracts import ReasoningEffort
+from convo.core.exceptions import BackendNotConnected
+from convo.prompts.schema import response_format
+
+
+async def complete_chatgpt(
+    access_token: str,
+    model: str,
+    instructions: str,
+    input_items: ResponseInputParam,
+    reasoning_effort: ReasoningEffort | None = None,
+    *,
+    structured: bool = False,
+) -> str:
+    """Return text only after a successful terminal response event."""
+    async with AsyncOpenAI(
+        api_key=access_token,
+        base_url="https://api.openai.com/v1",
+        max_retries=0,
+        timeout=90,
+    ) as client:
+        stream = await client.responses.create(
+            model=model,
+            instructions=instructions,
+            input=input_items,
+            store=False,
+            stream=True,
+            reasoning={"effort": reasoning_effort} if reasoning_effort is not None else omit,
+            text={"format": cast(ResponseFormatTextJSONSchemaConfigParam, response_format())}
+            if structured
+            else omit,
+        )
+        text: list[str] = []
+        completed = False
+        async with stream:
+            async for event in stream:
+                if event.type == "response.output_text.delta":
+                    text.append(event.delta)
+                elif event.type == "response.refusal.delta":
+                    raise BackendNotConnected(
+                        "ChatGPT declined this request. Try a different question."
+                    )
+                elif event.type == "response.failed":
+                    error = event.response.error
+                    code = error.code if error else "unknown_error"
+                    raise RuntimeError(f"ChatGPT response failed ({code})")
+                elif event.type == "response.incomplete":
+                    raise RuntimeError("ChatGPT response was incomplete")
+                elif event.type == "error":
+                    raise RuntimeError("ChatGPT stream returned an error")
+                elif event.type == "response.completed":
+                    completed = True
+        if not completed:
+            raise RuntimeError("ChatGPT stream ended before response.completed")
+    return "".join(text)

convo/migrations/env.py

@@ -0,0 +1,43 @@
+from alembic import context
+from sqlalchemy import create_engine, pool
+
+from convo.core.config import load_settings
+from convo.db import models as models
+from convo.db.base import Base
+
+config = context.config
+settings = load_settings()
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=settings.database_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    engine = create_engine(settings.database_url, poolclass=pool.NullPool)
+    try:
+        with engine.connect() as connection:
+            context.configure(
+                connection=connection,
+                target_metadata=target_metadata,
+                compare_type=True,
+            )
+            with context.begin_transaction():
+                context.run_migrations()
+    finally:
+        engine.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

convo/migrations/script.py.mako

@@ -0,0 +1,22 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+"""
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

convo/migrations/versions/5c3b75f9c5c1_describe_your_schema_change.py

@@ -0,0 +1,22 @@
+"""describe your schema change
+
+Revision ID: 5c3b75f9c5c1
+Revises: 732cf62e465c
+"""
+
+revision = "5c3b75f9c5c1"
+down_revision = "732cf62e465c"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###

convo/migrations/versions/732cf62e465c_create_rag_tables.py

@@ -0,0 +1,49 @@
+"""create rag tables
+
+Revision ID: 732cf62e465c
+Revises: None
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from pgvector.sqlalchemy import VECTOR
+
+revision = "732cf62e465c"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("CREATE EXTENSION IF NOT EXISTS vector")
+    op.create_table(
+        "documents",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("source_path", sa.Text(), nullable=False),
+        sa.Column("content_hash", sa.String(64), nullable=False),
+        sa.Column("index_signature", sa.Text(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name="pk_documents"),
+    )
+    op.create_table(
+        "chunks",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("document_id", sa.UUID(), nullable=False),
+        sa.Column("ordinal", sa.Integer(), nullable=False),
+        sa.Column("text", sa.Text(), nullable=False),
+        sa.Column("locator", sa.Text(), nullable=False),
+        sa.Column("embedding", VECTOR(1024), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["document_id"],
+            ["documents.id"],
+            name="fk_chunks_document_id_documents",
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name="pk_chunks"),
+        sa.UniqueConstraint("document_id", "ordinal", name="uq_chunks_document_id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("chunks")
+    op.drop_table("documents")
+    # Retain the extension: another application

convo/migrations/versions/README.md

@@ -0,0 +1,3 @@
+# Migration revisions
+
+Create the initial handwritten revision following backend.md step 4. It must enable the vector extension before creating the vector column. This folder contains no applied or generated revisions yet.