interactive-story/backend/app/routers/settings.py

"""The model settings, and the connection test that tells you why they don't work.

There is one settings row, belonging to the one local user. It describes an
Ollama: where it is, which model to narrate with, which to embed with, and how
long to wait for it.

Upstream let this row name any OpenAI-compatible endpoint and carry an
encrypted API key for it. M2 narrowed both: `endpoints.py` decides which
addresses may be named, and there is no key field, because Ollama does not use
one and this build has no cloud provider to carry a key for.
"""

import httpx
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from starlette.concurrency import run_in_threadpool

from .. import auth, endpoints, models, schemas, tlstrust
from ..database import get_db
from ..providers.openai_compatible import CONNECT_TIMEOUT

router = APIRouter(prefix="/api/settings", tags=["settings"])

#: The connection test is a listing, not a generation, so it never waits on a
#: model load and does not need the turn engine's patience.
TEST_TIMEOUT = 15.0


def get_settings(db: Session, user: models.User) -> models.Settings:
    """Returns the settings row, creating it on first access."""
    settings = (
        db.query(models.Settings).filter(models.Settings.user_id == user.id).first()
    )
    if settings is None:
        settings = models.Settings(user_id=user.id)
        db.add(settings)
        db.commit()
    return settings


@router.get("", response_model=schemas.SettingsOut)
def read_settings(
    db: Session = Depends(get_db),
    user: models.User = Depends(auth.get_current_user),
):
    return get_settings(db, user)


@router.put("", response_model=schemas.SettingsOut)
async def update_settings(
    payload: schemas.SettingsUpdate,
    db: Session = Depends(get_db),
    user: models.User = Depends(auth.get_current_user),
):
    settings = get_settings(db, user)
    fields = payload.model_dump(exclude_unset=True)

    if "endpoint_url" in fields:
        # Refused here so the user finds out while they are looking at the
        # field, rather than on their next turn. The provider re-checks before
        # every request regardless; this is the friendly half of the same rule.
        reason = await run_in_threadpool(
            endpoints.rejection_reason, fields["endpoint_url"]
        )
        if reason is not None:
            raise HTTPException(400, f"That endpoint can't be used — {reason}.")

    embedding_model_changed = (
        "embedding_model" in fields
        and fields["embedding_model"] != settings.embedding_model
    )
    for field, value in fields.items():
        setattr(settings, field, value)
    if embedding_model_changed:
        # Vectors from the old model have a different dimensionality/space;
        # clear them so the post-turn task re-embeds with the new model.
        #
        # Both columns, and the flag. This is the one place that clears vectors
        # in bulk rather than through memorybank.set_vector, and when the
        # vectors moved to embedding_blob it kept nulling the old JSON column
        # alone. The blob survived, `embedded` stayed true, and
        # `_embed_pending`, which selects rows where `embedded IS FALSE`, never
        # found the rows. The bank kept ranking against the previous model's
        # vectors.
        owned = (
            db.query(models.Adventure.id)
            .filter(models.Adventure.user_id == user.id)
            .scalar_subquery()
        )
        db.query(models.Memory).filter(models.Memory.adventure_id.in_(owned)).update(
            {"embedding_blob": None, "embedded": False}, synchronize_session=False
        )
        # No cache invalidation needed, and deliberately none added: clearing
        # `embedded` drops these rows out of the catalogue query, so retrieval
        # stops asking for them, and by the time _embed_pending puts one back
        # it has gone through set_vector, which evicts that entry. The rule
        # holds: anything that removes a memory from play corrects itself.
    db.commit()
    return settings


async def list_endpoint_models(endpoint_url: str) -> dict:
    """Fetches the endpoint's `/models` listing, and doubles as the connection test.

    Returns `{"ok": False, "detail": ...}` rather than raising, because every
    caller wants to show the reason rather than fail the page.

    The failure cases are told apart on purpose. "Ollama isn't running", "that
    address isn't allowed", "the certificate doesn't verify" and "it answered,
    but with an error" need four different things done about them, and a single
    "connection failed" leaves the user guessing which they have.
    """
    reason = await run_in_threadpool(endpoints.rejection_reason, endpoint_url)
    if reason is not None:
        return {
            "ok": False, "kind": "rejected",
            "detail": f"That endpoint can't be used — {reason}.",
        }

    url = endpoint_url.rstrip("/") + "/models"
    try:
        async with httpx.AsyncClient(
            timeout=httpx.Timeout(TEST_TIMEOUT, connect=CONNECT_TIMEOUT),
            verify=tlstrust.ssl_context(),
        ) as client:
            resp = await client.get(url)
    except httpx.ConnectError as exc:
        # A TLS failure arrives as a ConnectError too, and it needs a different
        # answer from "nothing is listening": install the CA, don't start Ollama.
        if "CERTIFICATE_VERIFY" in str(exc).upper() or "SSL" in str(exc).upper():
            return {
                "ok": False, "kind": "tls",
                "detail": (
                    "The endpoint's TLS certificate could not be verified. If it "
                    "uses a private or self-signed CA, install that CA on this "
                    "machine so the system trusts it. Certificate checking is "
                    "not optional."
                ),
            }
        return {
            "ok": False, "kind": "unreachable",
            "detail": f"Could not connect to {endpoint_url} — is Ollama running there?",
        }
    except httpx.TimeoutException:
        return {
            "ok": False, "kind": "timeout",
            "detail": f"{endpoint_url} did not answer within {TEST_TIMEOUT:.0f}s.",
        }
    except httpx.HTTPError as exc:
        return {"ok": False, "kind": "error", "detail": f"Connection failed: {exc}"}

    if resp.status_code != 200:
        return {
            "ok": False, "kind": "http",
            "detail": f"HTTP {resp.status_code}: {resp.text[:300]}",
        }

    models_available: list[str] = []
    try:
        data = resp.json()
        models_available = [m.get("id", "?") for m in data.get("data", [])]
    except (ValueError, AttributeError, TypeError):
        pass  # The body is not JSON or has an unexpected shape. The endpoint
        # is still reachable.
    return {"ok": True, "models": models_available}


@router.post("/test")
async def test_connection(
    db: Session = Depends(get_db),
    user: models.User = Depends(auth.get_current_user),
):
    """Checks the endpoint the turn engine would use, and lists its models."""
    settings = get_settings(db, user)
    result = await list_endpoint_models(settings.endpoint_url)
    if result.get("ok") and settings.model and settings.model not in result["models"]:
        # Reachable, but pointed at a model that is not installed there — the
        # commonest way for a correct endpoint to still fail every turn.
        return result | {
            "warning": (
                f"{settings.endpoint_url} is reachable, but has no model named "
                f"'{settings.model}'. Pull it there, or pick one from the list."
            )
        }
    return result