Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

4.0 KB
Raw Blame
"""Project-wide exception classes."""


class ResearchTerminatedException(BaseException):
    """Raised when a user cancels an in-progress research process.

    Inherits from BaseException (not Exception) so that ``except Exception``
    blocks throughout the strategy code naturally let it propagate -- the same
    pattern Python's stdlib uses for asyncio.CancelledError (since 3.9),
    KeyboardInterrupt, and SystemExit.
    """

    pass


class NoUserDatabaseError(RuntimeError):
    """Raised when a resolved user has no database to open.

    Subclasses ``RuntimeError`` deliberately: this condition was signalled by a
    bare ``RuntimeError`` before, and callers (plus
    ``tests/utilities/test_db_utils.py``) still catch and match on that. The
    subclass adds the ability to tell this case apart *without* changing what
    anything already catches.

    That distinction is the whole point. ``get_settings_manager`` used to catch
    every ``RuntimeError`` from ``get_db_session`` and fall back to anonymous
    defaults, which conflates three unrelated situations:

    1. This one — a known user with no database. Defaults are the only answer
       available, so the fallback is correct.
    2. A true background thread with no request context. That is a programming
       error the codebase already warns about in several places (#3453), and
       answering it with defaults means a worker silently reads *someone
       else's* configuration instead of the user's.
    3. Anything deeper failing inside ``db_manager.get_session`` — a corrupt or
       unopenable encrypted database, a keyring failure, or a rekey sidecar
       or epoch fault on the cached engine (raised as the typed
       ``RekeyOperationalError``, not answered with ``None``). Serving
       defaults here is the most dangerous of the three: a setting that is
       off by default silently reads as off, even though the user turned it
       on, and a stored ``strict`` egress scope reads as the default.

    Only case 1 should be swallowed. The other two must reach the caller.
    """

    pass


class SystemAtCapacityError(Exception):
    """Raised when ``start_research_process`` cannot acquire the global
    concurrency semaphore.

    Previously the semaphore was acquired *inside* the worker thread, so a
    full system would silently park the thread after the HTTP route had
    already returned 200 — the user saw a thinking spinner that never
    advanced, and the partial unique in-progress index blocked retries on
    the same chat session.

    Acquiring synchronously in the caller and surfacing this exception lets
    routes return HTTP 429 (or queue/retry, depending on caller) before any
    ``ResearchHistory`` row is committed.
    """

    pass


class DuplicateResearchError(Exception):
    """Raised when a research should not be (re-)spawned.

    Two triggering cases, both handled identically by callers:

    1. A live thread already exists in the active-research dict for this
       ``research_id`` — typically a retry after a prior attempt's
       post-spawn ``UserActiveResearch`` commit failed.
    2. The ``ResearchHistory.status`` is non-QUEUED (``IN_PROGRESS`` from
       a prior attempt's pre-spawn commit that succeeded; terminal
       ``COMPLETED`` / ``FAILED`` / ``SUSPENDED`` from a thread that
       already finished and cleaned itself out of ``_active_research``).
       Re-spawning would either contradict the live thread or re-run a
       finished research.

    Callers that wrap the spawn in ``except Exception`` to clean up orphan
    state on spawn failure MUST catch ``DuplicateResearchError`` separately
    *before* that generic branch and re-raise / return without mutating the
    research's status or deleting the ``UserActiveResearch`` row — those
    rows belong to the live thread, and marking them FAILED terminates a
    running thread from the user's perspective while it keeps executing.
    """

    pass


class InvalidQueuedResearchOverridesError(Exception):
    """Raised when persisted queued search overrides fail validation."""

    pass