Defer Typesense client setup for conversation search

[tianmind-studio]

Summary

• lazily initialize the conversation-search Typesense client so importing backend routers does not require TYPESENSE_* env vars
• validate missing Typesense config only when search is actually used, preserving config errors as RuntimeError
• guard first-use initialization with a lock so concurrent callers share one client
• add unit coverage for import-time safety, missing config, first-use construction, and concurrent initialization

Verification

• python -m pytest backend\tests\unit\test_conversation_search_typesense_config.py -q --tb=short -> 4 passed
• python -m py_compile backend\utils\conversations\search.py backend\tests\unit\test_conversation_search_typesense_config.py
• python -m black --line-length 120 --skip-string-normalization --check backend\utils\conversations\search.py backend\tests\unit\test_conversation_search_typesense_config.py
• PYTHONUTF8=1 python backend\scripts\scan_async_blockers.py -> no new blockers from this PR; existing backlog only
• git diff --check origin/main...HEAD
• scripts/pre-commit via Git for Windows sh.exe with the backend venv on PATH

Notes

• Rebased onto current main (9ed12aea07).
• Existing Greptile feedback remains addressed: first-use initialization is lock-guarded, missing config keeps its RuntimeError, and concurrent initialization coverage is included.

[greptile-apps]

Greptile Summary

This PR defers Typesense client construction from module-import time to first use, so importing utils.conversations.search (and any router that pulls it in) no longer requires TYPESENSE_* environment variables to be present. Focused unit tests and a test.sh entry accompany the change.

• _get_typesense_client() replaces the module-level typesense.Client(...) call with a lazy singleton, validating all three env vars only when search is first invoked.
• Three new unit tests verify that import succeeds without env vars, that a missing TYPESENSE_API_KEY raises at call time, and that a successful first call constructs the client with the expected config.
• The singleton is not guarded by a lock, so concurrent first-calls can create duplicate typesense.Client instances (minor, benign in CPython due to the GIL, but worth hardening). The existing broad except Exception catch also repackages the config RuntimeError as a generic Exception, which may complicate error-type-based handling upstream.

Confidence Score: 4/5

Safe to merge — the lazy-init change is self-contained, the tests cover the main scenarios, and the identified concerns are non-blocking quality improvements.

The core change is straightforward and achieves its goal. The singleton lacks a threading lock (benign in practice but not future-proof), and the broad exception handler silently changes the type of config errors, making them harder to distinguish from runtime search failures. Neither issue causes incorrect behavior today.

backend/utils/conversations/search.py — the singleton initialization pattern and exception-wrapping logic are the two spots worth a second look before this pattern is replicated elsewhere.

Important Files Changed

Filename	Overview
backend/utils/conversations/search.py	Replaces module-level Typesense client construction with a lazy singleton; _get_typesense_client() defers env-var validation to first use. The singleton is not guarded by a lock (minor race under concurrency), and config RuntimeError is swallowed by the pre-existing broad except block.
backend/tests/unit/test_conversation_search_typesense_config.py	New unit tests cover import-time safety, missing-env-var error on first use, and successful client construction. Module isolation via sys.modules.pop is correct. Missing a test asserting that the second call reuses the cached client rather than constructing a new one.
backend/test.sh	Adds the new test file to the CI test script in the correct position alongside similar unit tests; no issues.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant search_conversations
    participant _get_typesense_client
    participant typesense.Client

    Caller->>search_conversations: search_conversations(uid, query)
    search_conversations->>_get_typesense_client: _get_typesense_client()
    alt _typesense_client is None
        _get_typesense_client->>_get_typesense_client: _get_required_env_var(TYPESENSE_HOST)
        _get_typesense_client->>_get_typesense_client: _get_required_env_var(TYPESENSE_HOST_PORT)
        _get_typesense_client->>_get_typesense_client: _get_required_env_var(TYPESENSE_API_KEY)
        note over _get_typesense_client: raises RuntimeError if any var missing
        _get_typesense_client->>typesense.Client: Client(config)
        typesense.Client-->>_get_typesense_client: client instance
        _get_typesense_client->>_get_typesense_client: "_typesense_client = client (cached)"
    else _typesense_client already initialized
        note over _get_typesense_client: return cached singleton
    end
    _get_typesense_client-->>search_conversations: client
    search_conversations->>typesense.Client: collections['conversations'].documents.search(params)
    typesense.Client-->>search_conversations: results
    search_conversations-->>Caller: "{items, total_pages, current_page, per_page}"

Loading

Comments Outside Diff (1)

1. backend/utils/conversations/search.py, line 87-88 (link)

   Config RuntimeError is repackaged as a generic Exception

   When _get_required_env_var raises RuntimeError (missing env vars), the outer except Exception catch-all wraps it into a plain Exception("Failed to search conversations: ..."). This changes the exception type, so callers cannot use except RuntimeError to distinguish a misconfiguration from a network/search error. The tests pass because pytest.raises matches the substring, but any production error-handling code that inspects exception type will treat a missing TYPESENSE_API_KEY identically to a Typesense timeout. Letting the RuntimeError propagate uncaught (or re-raising it explicitly before the broad catch) would preserve the distinction.

_{Reviews (1): Last reviewed commit: "Defer Typesense client setup for convers..." | Re-trigger Greptile}

[kodjima33]

Lazy Typesense client init — backend refactor with tests, approve only per backend policy.

[tianmind-studio]

I rebased and force-pushed this branch onto the current main. The latest commit includes the review follow-ups: lazy initialization is lock-guarded, missing config remains a RuntimeError, and there is a concurrent first-use test. I reran python -m pytest tests\unit\test_conversation_search_typesense_config.py -q: 4 passed.

[kodjima33]

re-approved on new sha: backend bug fix (lazy Typesense client init + concurrency lock) — approve only

[kodjima33]

Re-approved on new sha: lazy Typesense init — has merge conflicts, please rebase

[kodjima33]

Lazy Typesense init w/ tests — re-approved on new sha