~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
Utility functions for handling research context propagation.
This module provides helpers for propagating research context across thread
and asyncio boundaries. Built on ``contextvars.ContextVar`` so the context
is correctly inherited by frameworks that copy the context to worker
threads (e.g. langchain's ``ContextThreadPoolExecutor`` used by LangGraph
for parallel tool execution). For stdlib ``ThreadPoolExecutor`` — which
does not copy context — use ``preserve_research_context`` below.
"""
import functools
from contextlib import contextmanager
from contextvars import ContextVar
from typing import Any, Callable, Dict, Generator, Optional
from loguru import logger
_search_context_var: ContextVar[Optional[Dict[str, Any]]] = ContextVar(
"ldr_search_context", default=None
)
def set_search_context(context: Dict[str, Any]) -> None:
"""
Sets the research context for the current execution context.
Args:
context: The context to set.
"""
if _search_context_var.get() is not None:
logger.debug(
"Context already set for this thread. It will be overwritten."
)
_search_context_var.set(context.copy())
def clear_search_context() -> None:
"""
Clears the research context for the current execution context.
Should be called in a finally block after set_search_context() to prevent
context from leaking to subsequent tasks when threads are reused in a pool.
"""
_search_context_var.set(None)
def get_search_context() -> Dict[str, Any] | None:
"""
Gets the current research context.
Returns:
The context dictionary, or None if no context is set.
"""
context = _search_context_var.get()
if context is not None:
context = context.copy()
return context
def resolve_fetch_identity(
egress_context: Any = None,
settings_snapshot: Optional[Dict[str, Any]] = None,
username: Optional[str] = None,
password: Optional[str] = None,
) -> tuple[Optional[str], Optional[str], Optional[Dict[str, Any]]]:
"""Centralize fetch-time identity resolution in one helper.
Precedence: explicit args > egress_context > thread search context >
settings snapshot ``_username``. Never raises; missing identity yields
``None`` so callers can skip persistence gracefully.
"""
if username is None and egress_context is not None:
username = getattr(egress_context, "username", None)
if password is None and egress_context is not None:
password = getattr(egress_context, "password", None)
if (not username or not password or not settings_snapshot) and True:
try:
ctx = get_search_context()
if ctx and isinstance(ctx, dict):
if not username:
username = ctx.get("username")
if not password:
password = ctx.get("user_password")
if not settings_snapshot:
snap = ctx.get("settings_snapshot")
if isinstance(snap, dict):
settings_snapshot = snap
except Exception: # allow: silent-exception
pass
if not username and isinstance(settings_snapshot, dict):
try:
from ..search_system import username_from_snapshot
snap_user = username_from_snapshot(settings_snapshot)
if snap_user:
username = snap_user
except Exception: # allow: silent-exception
pass
return username, password, settings_snapshot
@contextmanager
def search_context(context: Dict[str, Any]) -> Generator[None, None, None]:
"""Context manager that sets and clears search context automatically.
Ensures cleanup even if an exception occurs, preventing context leaks
when threads are reused in a pool.
Example:
with search_context({"research_id": "123"}):
results = engine.run(query)
"""
set_search_context(context)
try:
yield
finally:
clear_search_context()
def preserve_research_context(func: Callable) -> Callable:
"""
Decorator that preserves research context across thread boundaries.
Use this decorator on functions that will be executed in ThreadPoolExecutor
to ensure the research context (including research_id) is properly propagated.
When metrics are disabled (e.g., in programmatic mode), this decorator
safely does nothing to avoid database dependencies.
Example:
@preserve_research_context
def search_task(query):
return search_engine.run(query)
"""
# Try to capture current context, but don't fail if it's not set. There
# are legitimate cases where it might not be set, such as for
# programmatic access.
context = get_search_context()
# Capture the submitter thread's egress audit-hook context too. Unlike the
# search context (a ContextVar that langchain's executors copy), the audit
# context lives in a threading.local that stdlib ThreadPoolExecutor workers
# do NOT inherit — so without re-arming it here the PEP-578 socket backstop
# would be inactive on every pool worker. Capture once on the submitter
# thread; re-arm + clear per task below.
try:
from ..security.egress.audit_hook import (
get_active_context as _get_egress_ctx,
)
egress_ctx = _get_egress_ctx()
except Exception:
egress_ctx = None
@functools.wraps(func)
def wrapper(*args, **kwargs):
if context is not None:
set_search_context(context)
if egress_ctx is not None:
from ..security.egress.audit_hook import (
set_active_context as _set_egress_ctx,
)
_set_egress_ctx(egress_ctx)
try:
return func(*args, **kwargs)
finally:
if egress_ctx is not None:
from ..security.egress.audit_hook import (
clear_active_context as _clear_egress_ctx,
)
_clear_egress_ctx()
if context is not None:
clear_search_context()
# Clean up thread-local DB engines created by metrics recording
try:
from ..database.thread_local_session import (
cleanup_current_thread,
)
cleanup_current_thread()
except Exception:
logger.debug(
"preserve_research_context: error during cleanup_current_thread",
exc_info=True,
)
return wrapper