~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
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
from ..dependencies.auth import require_auth
from ..dependencies.threadpool import run_db_sync
import requests
from loguru import logger
from ...llm.providers.base import normalize_provider
from ...constants import ResearchStatus
from ...database.models import QueuedResearch, ResearchHistory
from ...database.session_context import get_user_db_session
from ...config.constants import DEFAULT_OLLAMA_URL
from ...utilities.url_utils import normalize_url
from .notes import _log_value_preview
from .research import _research_not_found
from ..services.research_service import (
cancel_research,
)
from ..services.resource_service import (
add_resource,
delete_resource,
get_resources_for_research,
)
from local_deep_research.settings import SettingsManager
from ...security import redact_url_for_log, safe_get, strip_settings_snapshot
from ..dependencies.json_body import (
is_json_request,
json_body_error,
read_json_dict,
)
from typing import Annotated
# Create the router
router = APIRouter(prefix="/research/api", tags=["api"])
# NOTE: Routes use username (not .get()) intentionally.
# Depends(require_auth) guarantees the key exists; direct access fails
# fast if the dependency is ever removed.
@router.get("/settings/current-config")
def get_current_config(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""Get the current configuration from database settings."""
try:
with get_user_db_session(username) as session:
settings_manager = SettingsManager(session)
config = {
"provider": settings_manager.get_setting(
"llm.provider", "Not configured"
),
"model": settings_manager.get_setting(
"llm.model", "Not configured"
),
"search_tool": settings_manager.get_setting(
"search.tool", "searxng"
),
"iterations": settings_manager.get_setting(
"search.iterations", 8
),
"questions_per_iteration": settings_manager.get_setting(
"search.questions_per_iteration", 5
),
"search_strategy": settings_manager.get_setting(
"search.search_strategy", "focused_iteration"
),
}
return {"success": True, "config": config}
except Exception:
logger.exception("Error getting current config")
return JSONResponse(
{"success": False, "error": "An internal error occurred"},
status_code=500,
)
# API Routes
@router.post("/start")
async def api_start_research(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
Start a new research process.
Delegates to the full-featured start_research() in the research router,
which reads settings from the database, handles queueing, and starts
the research thread.
"""
from .research import start_research
return await start_research(request=request, username=username)
@router.get("/status/{research_id}")
def api_research_status(
request: Request,
research_id,
username: Annotated[str, Depends(require_auth)],
):
"""
Get the status of a research process
"""
try:
# Get a fresh session to avoid conflicts with the research process
with get_user_db_session(username) as db_session:
research = (
db_session.query(ResearchHistory)
.filter_by(id=research_id)
.first()
)
if research is None:
return _research_not_found(research_id)
# Extract attributes while session is active
# to avoid DetachedInstanceError after the with block exits
result = {
"status": research.status,
"progress": research.progress,
"completed_at": research.completed_at,
# report_path deliberately omitted: absolute server-side
# path, which leaks directory layout — same rule as
# /library/api/check-downloads and the history
# status/detail endpoints.
"metadata": strip_settings_snapshot(research.research_meta),
}
# Include queue position for queued research so the progress
# page can show "position N in queue" (#3283).
if research.status == ResearchStatus.QUEUED:
queued = (
db_session.query(QueuedResearch)
.filter_by(research_id=research_id)
.first()
)
if queued:
result["queue_position"] = queued.position
return result
except Exception:
logger.exception("Error getting research status")
return JSONResponse(
{"status": "error", "message": "Failed to get research status"},
status_code=500,
)
@router.post("/terminate/{research_id}")
def api_terminate_research(
request: Request,
research_id,
username: Annotated[str, Depends(require_auth)],
):
"""
Terminate a research process
"""
try:
result = cancel_research(research_id, username)
if result:
return {
"status": "success",
"message": "Research terminated",
"result": result,
}
return {
"status": "success",
"message": "Research not found or already completed",
"result": result,
}
except Exception:
logger.exception("Error terminating research")
return JSONResponse(
{"status": "error", "message": "Failed to stop research."},
status_code=500,
)
@router.get("/resources/{research_id}")
def api_get_resources(
request: Request,
research_id,
username: Annotated[str, Depends(require_auth)],
):
"""
Get resources for a specific research.
User-scoped: each user has their own encrypted database, so a
``research_id`` belonging to another user simply yields an empty
list rather than leaking their data.
"""
try:
resources = get_resources_for_research(research_id, username)
return {"status": "success", "resources": resources}
except Exception:
logger.exception("Error getting resources for research")
return JSONResponse(
{"status": "error", "message": "Failed to get resources"},
status_code=500,
)
@router.post("/resources/{research_id}")
async def api_add_resource(
request: Request,
research_id,
username: Annotated[str, Depends(require_auth)],
):
"""
Add a new resource to a research project
"""
if not is_json_request(request):
return json_body_error("status", "Request body must be valid JSON")
data, error = await read_json_dict(request, "status")
if error is not None:
return error
def _impl():
try:
# Required fields
title = data.get("title")
url = data.get("url")
# Optional fields
content_preview = data.get("content_preview")
source_type = data.get("source_type", "web")
metadata = data.get("metadata", {})
# Validate required fields
if not title or not url:
return JSONResponse(
{
"status": "error",
"message": "Title and URL are required",
},
status_code=400,
)
# Security: Validate URL to prevent SSRF attacks
from ...security.ssrf_validator import validate_url
is_valid = validate_url(url)
if not is_valid:
if isinstance(url, str):
logger.warning(
"SSRF protection: Rejected URL {}",
_log_value_preview(redact_url_for_log(url)),
)
else:
logger.warning("SSRF protection: Rejected URL (non-string)")
return JSONResponse(
{"status": "error", "message": "Invalid URL"},
status_code=400,
)
# Check if the research exists
with get_user_db_session(username) as db_session:
research = (
db_session.query(ResearchHistory)
.filter_by(id=research_id)
.first()
)
if not research:
return _research_not_found(research_id)
# Add the resource
resource_id = add_resource(
research_id=research_id,
title=title,
url=url,
content_preview=content_preview,
source_type=source_type,
metadata=metadata,
username=username,
)
return {
"status": "success",
"message": "Resource added successfully",
"resource_id": resource_id,
}
except Exception:
logger.exception("Error adding resource")
return JSONResponse(
{"status": "error", "message": "Failed to add resource"},
status_code=500,
)
return await run_db_sync(_impl)
@router.delete("/resources/{research_id}/delete/{resource_id}")
def api_delete_resource(
request: Request,
research_id,
# Typed int, matching Flask's <int:resource_id> converter: without it a
# non-numeric segment is passed straight through to the service layer
# instead of being rejected as a 422 by the router.
resource_id: int,
username: Annotated[str, Depends(require_auth)],
):
"""
Delete a resource from a research project
"""
try:
# delete_resource() always returns True or raises ValueError("...
# not found") — never False — so the not-found case is handled by
# the except ValueError below, not by checking the return value.
delete_resource(resource_id, username=username)
return {
"status": "success",
"message": "Resource deleted successfully",
}
except ValueError:
return JSONResponse(
{"status": "error", "message": "Resource not found"},
status_code=404,
)
except Exception:
logger.exception("Error deleting resource")
return JSONResponse(
{
"status": "error",
"message": "An internal error occurred while deleting the resource.",
},
status_code=500,
)
def _ollama_base_url_from_config(raw_ollama_base_url):
"""Resolve the Ollama base URL from a raw setting value (normalized, with
the default fallback). Single source so every Ollama probe targets the
same URL."""
return (
normalize_url(raw_ollama_base_url)
if raw_ollama_base_url
else DEFAULT_OLLAMA_URL
)
def _probe_ollama_tags(base_url, timeout=5):
"""Probe Ollama ``/api/tags`` once and classify the outcome.
Single source for the resolve→fetch→new/old-format-parse→error logic that
was previously copy-pasted across the status and model-availability checks
(so "is Ollama up?" can no longer answer differently per caller). Returns
``(outcome, probe_result)`` where outcome is one of:
- ``"ok"`` → probe_result is the list of model dicts (both API formats handled)
- ``"bad_status"`` → probe_result is the non-200 status code
- ``"invalid_json"`` → probe_result is None (200 but unparseable body)
- ``"connection_error"`` / ``"timeout"`` → probe_result is None
Callers map the outcome onto their own response shape.
"""
try:
response = safe_get(
f"{base_url}/api/tags",
timeout=timeout,
allow_localhost=True,
allow_private_ips=True,
)
except requests.exceptions.ConnectionError:
return "connection_error", None
except requests.exceptions.Timeout:
return "timeout", None
if response.status_code != 200:
return "bad_status", response.status_code
try:
data = response.json()
except ValueError:
return "invalid_json", None
# New Ollama API nests the list under "models"; the older format is a
# bare list. Mirror the previous inline check exactly (a bare ``"models"
# in data`` membership test, no isinstance guard) so behavior is identical
# to the pre-refactor endpoints — a malformed non-dict/non-list body
# raises here and is handled by each caller's outer except, as before.
if "models" in data:
models = data.get("models", [])
else:
models = data
return "ok", models
@router.get("/check/ollama_status")
def check_ollama_status(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
Check if Ollama API is running
"""
try:
# Get the Ollama provider/URL from the user's settings (the Flask
# version read these from app.config["LLM_CONFIG"]).
with get_user_db_session(username) as session:
settings_manager = SettingsManager(session)
provider = settings_manager.get_setting("llm.provider", "ollama")
raw_ollama_base_url = settings_manager.get_setting(
"llm.ollama.url", DEFAULT_OLLAMA_URL
)
if normalize_provider(provider) != "ollama":
return {
"running": True,
"message": f"Using provider: {provider}, not Ollama",
}
ollama_base_url = _ollama_base_url_from_config(raw_ollama_base_url)
logger.info(
f"Checking Ollama status at: {redact_url_for_log(ollama_base_url)}"
)
outcome, probe_result = _probe_ollama_tags(ollama_base_url)
if outcome == "ok":
model_count = len(probe_result)
logger.info(f"Ollama service is running with {model_count} models")
return {
"running": True,
"message": f"Ollama service is running with {model_count} models",
"model_count": model_count,
}
if outcome == "invalid_json":
logger.warning("Ollama returned invalid JSON")
return {
"running": True,
"message": "Ollama service is running but returned invalid data format",
"error_details": "Invalid response format from the service.",
}
if outcome == "bad_status":
logger.warning(
f"Ollama returned non-200 status code: {probe_result}"
)
return {
"running": False,
"message": f"Ollama service returned status code: {probe_result}",
"status_code": probe_result,
}
if outcome == "connection_error":
logger.warning("Ollama connection error")
return {
"running": False,
"message": "Ollama service is not running or not accessible",
"error_type": "connection_error",
"error_details": "Unable to connect to the service. Please check if the service is running.",
}
# outcome == "timeout"
logger.warning("Ollama request timed out")
return {
"running": False,
"message": "Ollama service request timed out after 5 seconds",
"error_type": "timeout",
"error_details": "Request timed out. The service may be overloaded.",
}
except Exception:
logger.exception("Error checking Ollama status")
return {
"running": False,
"message": "An internal error occurred while checking Ollama status.",
"error_type": "exception",
"error_details": "An internal error occurred.",
}
@router.get("/check/ollama_model")
def check_ollama_model(
request: Request, username: Annotated[str, Depends(require_auth)]
):
"""
Check if the configured Ollama model is available
"""
try:
# Get the Ollama provider/model/URL from the user's settings (the
# Flask version read these from app.config["LLM_CONFIG"]).
with get_user_db_session(username) as session:
settings_manager = SettingsManager(session)
provider = settings_manager.get_setting("llm.provider", "ollama")
configured_model = settings_manager.get_setting("llm.model", "")
raw_ollama_base_url = settings_manager.get_setting(
"llm.ollama.url", DEFAULT_OLLAMA_URL
)
if normalize_provider(provider) != "ollama":
return {
"available": True,
"message": f"Using provider: {provider}, not Ollama",
"provider": provider,
}
# Get model name from request or fall back to the configured default
model_name = request.query_params.get("model")
if not model_name:
model_name = configured_model
if not model_name:
logger.warning(
"/api/check/ollama_model called with no model name and "
"llm.model is not configured"
)
return JSONResponse(
{
"available": False,
"model": "",
"message": (
"Model is required. Pass ?model=<name> in the "
"query string, or configure llm.model in Settings."
),
"error_type": "model_not_configured",
},
status_code=400,
)
# Log which model we're checking for debugging
logger.info(
f"Checking availability of Ollama model: {_log_value_preview(model_name)}"
)
ollama_base_url = _ollama_base_url_from_config(raw_ollama_base_url)
outcome, probe_result = _probe_ollama_tags(ollama_base_url)
if outcome == "bad_status":
logger.warning(
f"Ollama API returned non-200 status: {probe_result}"
)
return {
"available": False,
"model": model_name,
"message": f"Could not access Ollama service - status code: {probe_result}",
"status_code": probe_result,
}
if outcome == "invalid_json":
logger.warning("Failed to parse Ollama API response")
return {
"available": False,
"model": model_name,
"message": "Invalid response from Ollama API",
"error_type": "json_parse_error",
}
if outcome == "connection_error":
logger.warning("Connection error to Ollama API")
return {
"available": False,
"model": model_name,
"message": "Could not connect to Ollama service",
"error_type": "connection_error",
"error_details": "Unable to connect to the service. Please check if the service is running.",
}
if outcome == "timeout":
logger.warning("Timeout connecting to Ollama API")
return {
"available": False,
"model": model_name,
"message": "Connection to Ollama service timed out",
"error_type": "timeout",
}
# outcome == "ok"
models = probe_result
model_names = [m.get("name", "") for m in models]
logger.debug(
f"Available Ollama models: {', '.join(model_names[:10])}"
+ (
f" and {len(model_names) - 10} more"
if len(model_names) > 10
else ""
)
)
# Case-insensitive model name comparison
model_exists = any(
m.get("name", "").lower() == model_name.lower() for m in models
)
if model_exists:
logger.info(f"Ollama model {model_name} is available")
return {
"available": True,
"model": model_name,
"message": f"Model {model_name} is available",
"all_models": model_names,
}
# Check if models were found at all
if not models:
logger.warning("No models found in Ollama")
message = "No models found in Ollama. Please pull models first."
else:
logger.warning(
f"Model {_log_value_preview(model_name)} not found among {len(models)} available models"
)
# Don't expose available models for security reasons
message = f"Model {model_name} is not available"
return {
"available": False,
"model": model_name,
"message": message,
# Remove all_models to prevent information disclosure
}
except Exception:
# General exception
logger.exception("Error checking Ollama model")
return {
"available": False,
"model": model_name if "model_name" in locals() else "",
"message": "An internal error occurred while checking the model.",
"error_type": "exception",
"error_details": "An internal error occurred.",
}