Coverage for src / local_deep_research / constants.py: 100%

1"""Project-wide constants for Local Deep Research.""" 

2 

3from enum import StrEnum 

4 

5from .__version__ import __version__ 

6 

7# Honest, identifying User-Agent for APIs that prefer/require identification 

8# (e.g., academic APIs like arXiv, PubMed, OpenAlex) 

9USER_AGENT = ( 

10 f"Local-Deep-Research/{__version__} " 

11 "(Academic Research Tool; https://github.com/LearningCircuit/local-deep-research)" 

12) 

13 

14# Browser-like User-Agent for sites that may block bot requests 

15# Use sparingly and only when necessary 

16BROWSER_USER_AGENT = ( 

17 "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " 

18 "AppleWebKit/537.36 (KHTML, like Gecko) " 

19 "Chrome/120.0.0.0 Safari/537.36" 

20) 

21 

22 

23# --- Research status values --- 

24class ResearchStatus(StrEnum): 

25 """Status values for research records. 

26 

27 Uses StrEnum so values compare equal to plain strings, 

28 e.g. ``ResearchStatus.COMPLETED == "completed"`` is True. 

29 

30 Lifecycle:: 

31 

32 [*] ─┬─► QUEUED ─┬─► IN_PROGRESS ─┬─► COMPLETED 

33 │ │ ├─► FAILED 

34 │ └─► SUSPENDED └─► SUSPENDED 

35 │ (concurrency limit) (terminated while queued) 

36 │ 

37 └─► IN_PROGRESS (slots available, skips queue) 

38 

39 Notes: 

40 - PENDING is declared as a model default but no creation path 

41 actually sets it. All routes use QUEUED or IN_PROGRESS. 

42 - ERROR is checked as a terminal state but never set by current 

43 code. It predates FAILED and exists for backward compatibility 

44 with older database records. 

45 - CANCELLED is not used by the research workflow. It is used by 

46 the benchmark subsystem (BenchmarkStatus, BenchmarkTaskStatus). 

47 """ 

48 

49 # --- Active lifecycle states --- 

50 PENDING = "pending" # Model default; never set by any creation path 

51 QUEUED = "queued" # Waiting for a worker slot 

52 IN_PROGRESS = "in_progress" # Worker actively executing 

53 

54 # --- Terminal states --- 

55 COMPLETED = "completed" # Finished successfully 

56 SUSPENDED = "suspended" # User terminated the research 

57 FAILED = "failed" # Unrecoverable error during execution 

58 

59 # --- Legacy / compatibility --- 

60 ERROR = "error" # Never set; predates FAILED 

61 CANCELLED = "cancelled" # Unused by research; for benchmarks 

62 

63 

64# --- Rate limiting defaults --- 

65RATE_LIMIT_WINDOW_SECONDS = 60 

66DEFAULT_RATE_LIMIT = 60 # requests per window 

67 

68# --- Snippet / truncation lengths --- 

69SNIPPET_LENGTH_SHORT = 250 

70SNIPPET_LENGTH_LONG = 500