1  """
  2  Centralized constants for Ag3ntum.
  3  
  4  All magic numbers, strings, and configuration values are defined here.
  5  This ensures consistency across modules and makes maintenance easier.
  6  
  7  Usage:
  8      from .constants import (
  9          AnsiColors,
 10          BoxChars,
 11          StatusIcons,
 12          TerminalControl,
 13          LOG_FORMAT_FILE,
 14          LOG_PREVIEW_LENGTH,
 15      )
 16  """
 17  from enum import StrEnum
 18  
 19  
 20  # =============================================================================
 21  # Logging Constants
 22  # =============================================================================
 23  
 24  # Log format for file-based logging
 25  LOG_FORMAT_FILE: str = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
 26  
 27  # Log format for console (basic, no colors)
 28  LOG_FORMAT_CONSOLE: str = "%(levelname)-8s %(name)s: %(message)s"
 29  
 30  # Log format for colored console (using colorlog)
 31  LOG_FORMAT_COLORED: str = (
 32      "%(log_color)s%(levelname)-8s%(reset)s %(cyan)s%(name)s%(reset)s: %(message)s"
 33  )
 34  
 35  # Rotating file handler settings
 36  LOG_MAX_BYTES: int = 10 * 1024 * 1024  # 10 MB
 37  LOG_BACKUP_COUNT: int = 5
 38  
 39  # Log file names
 40  LOG_FILE_CLI: str = "agent_cli.log"
 41  LOG_FILE_HTTP: str = "agent_http.log"
 42  LOG_FILE_BACKEND: str = "backend.log"
 43  
 44  
 45  # =============================================================================
 46  # ANSI Terminal Colors
 47  # =============================================================================
 48  
 49  class AnsiColors(StrEnum):
 50      """
 51      ANSI escape codes for terminal colors.
 52  
 53      Single source of truth for all color codes used in terminal output.
 54      Used by both output.py and tracer.py for consistent styling.
 55      """
 56      RESET = "\033[0m"
 57      BOLD = "\033[1m"
 58      DIM = "\033[2m"
 59      ITALIC = "\033[3m"
 60      UNDERLINE = "\033[4m"
 61  
 62      # Standard foreground colors
 63      BLACK = "\033[30m"
 64      RED = "\033[31m"
 65      GREEN = "\033[32m"
 66      YELLOW = "\033[33m"
 67      BLUE = "\033[34m"
 68      MAGENTA = "\033[35m"
 69      CYAN = "\033[36m"
 70      WHITE = "\033[37m"
 71  
 72      # Bright foreground colors
 73      BRIGHT_BLACK = "\033[90m"
 74      BRIGHT_RED = "\033[91m"
 75      BRIGHT_GREEN = "\033[92m"
 76      BRIGHT_YELLOW = "\033[93m"
 77      BRIGHT_BLUE = "\033[94m"
 78      BRIGHT_MAGENTA = "\033[95m"
 79      BRIGHT_CYAN = "\033[96m"
 80      BRIGHT_WHITE = "\033[97m"
 81  
 82      # Background colors
 83      BG_BLACK = "\033[40m"
 84      BG_RED = "\033[41m"
 85      BG_GREEN = "\033[42m"
 86      BG_YELLOW = "\033[43m"
 87      BG_BLUE = "\033[44m"
 88      BG_MAGENTA = "\033[45m"
 89      BG_CYAN = "\033[46m"
 90      BG_WHITE = "\033[47m"
 91  
 92      # Semantic aliases for common use cases
 93      GRAY = "\033[90m"
 94      INFO = "\033[94m"
 95      SUCCESS = "\033[92m"
 96      WARNING = "\033[93m"
 97      ERROR = "\033[91m"
 98  
 99  
100  # =============================================================================
101  # Terminal Control Sequences
102  # =============================================================================
103  
104  class TerminalControl:
105      """ANSI escape sequences for terminal cursor and line control."""
106      CLEAR_LINE: str = "\033[2K"
107      CURSOR_UP: str = "\033[1A"
108      CURSOR_DOWN: str = "\033[1B"
109      CURSOR_START: str = "\033[0G"
110      CURSOR_HIDE: str = "\033[?25l"
111      CURSOR_SHOW: str = "\033[?25h"
112      SAVE_CURSOR: str = "\033[s"
113      RESTORE_CURSOR: str = "\033[u"
114  
115      @staticmethod
116      def move_up(n: int = 1) -> str:
117          """Move cursor up n lines."""
118          return f"\033[{n}A"
119  
120      @staticmethod
121      def move_down(n: int = 1) -> str:
122          """Move cursor down n lines."""
123          return f"\033[{n}B"
124  
125      @staticmethod
126      def move_to_column(col: int) -> str:
127          """Move cursor to column position."""
128          return f"\033[{col}G"
129  
130  
131  # =============================================================================
132  # Color Configuration for colorlog
133  # =============================================================================
134  
135  COLORLOG_COLORS: dict[str, str] = {
136      "DEBUG": "white",
137      "INFO": "green",
138      "WARNING": "yellow",
139      "ERROR": "red",
140      "CRITICAL": "red,bg_white",
141  }
142  
143  
144  # =============================================================================
145  # Display Constants
146  # =============================================================================
147  
148  # Preview lengths for logging and display
149  LOG_PREVIEW_LENGTH: int = 100
150  TASK_PREVIEW_LENGTH: int = 60
151  ERROR_PREVIEW_LENGTH: int = 40
152  WORKING_DIR_TRUNCATE_LENGTH: int = 40
153  MESSAGE_PREVIEW_LENGTH: int = 80
154  TOOL_PREVIEW_LENGTH: int = 80
155  PATH_TRUNCATE_LENGTH: int = 80
156  
157  # Terminal output
158  DEFAULT_TERMINAL_WIDTH: int = 80
159  MIN_TERMINAL_WIDTH: int = 50
160  MAX_TERMINAL_WIDTH: int = 120
161  RESULT_BOX_MAX_WIDTH: int = 55
162  
163  # Session table column widths
164  SESSION_ID_WIDTH: int = 30
165  SESSION_STATUS_WIDTH: int = 12
166  SESSION_CREATED_WIDTH: int = 20
167  
168  
169  # =============================================================================
170  # Box Drawing Characters (Unicode)
171  # =============================================================================
172  
173  class BoxChars:
174      """
175      Unicode box drawing characters for terminal output.
176  
177      Single source of truth for all box/border characters used in CLI display.
178      Provides both single-line and double-line variants.
179      """
180      # Single-line box
181      TOP_LEFT: str = "┌"
182      TOP_RIGHT: str = "┐"
183      BOTTOM_LEFT: str = "└"
184      BOTTOM_RIGHT: str = "┘"
185      HORIZONTAL: str = "─"
186      VERTICAL: str = "│"
187      LEFT_T: str = "├"
188      RIGHT_T: str = "┤"
189      TOP_T: str = "┬"
190      BOTTOM_T: str = "┴"
191      CROSS: str = "┼"
192  
193      # Double-line box
194      DOUBLE_TOP_LEFT: str = "╔"
195      DOUBLE_TOP_RIGHT: str = "╗"
196      DOUBLE_BOTTOM_LEFT: str = "╚"
197      DOUBLE_BOTTOM_RIGHT: str = "╝"
198      DOUBLE_HORIZONTAL: str = "═"
199      DOUBLE_VERTICAL: str = "║"
200  
201      # ASCII fallbacks for non-Unicode terminals
202      ASCII_TOP_LEFT: str = "+"
203      ASCII_TOP_RIGHT: str = "+"
204      ASCII_BOTTOM_LEFT: str = "+"
205      ASCII_BOTTOM_RIGHT: str = "+"
206      ASCII_HORIZONTAL: str = "-"
207      ASCII_VERTICAL: str = "|"
208  
209  
210  # =============================================================================
211  # Status and Decoration Icons
212  # =============================================================================
213  
214  class StatusIcons:
215      """
216      Unicode icons for status display.
217  
218      Single source of truth for all status indicators used in terminal output.
219      """
220      # Status indicators
221      SUCCESS: str = "✓"
222      FAILURE: str = "✗"
223      WARNING: str = "⚠"
224      INFO: str = "ℹ"
225      RUNNING: str = "⟳"
226      PENDING: str = "○"
227  
228      # Additional decorative symbols
229      BULLET: str = "•"
230      CIRCLE: str = "○"
231      CIRCLE_FILLED: str = "●"
232      STAR: str = "★"
233      LIGHTNING: str = "⚡"
234      GEAR: str = "⚙"
235      POINTER: str = "❯"
236      ARROW_RIGHT: str = "→"
237      ARROW_LEFT: str = "←"
238      ARROW_UP: str = "↑"
239      ARROW_DOWN: str = "↓"
240      TRIANGLE_RIGHT: str = "▶"
241      TRIANGLE_DOWN: str = "▼"
242      FOLDER: str = "▣"
243      FILE: str = "▫"
244      CLOCK: str = "◔"
245      BRAIN: str = "◆"
246  
247      # Spinner characters for progress indication
248      SPINNER: tuple[str, ...] = (
249          "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"
250      )
251      SPINNER_LINE: tuple[str, ...] = ("—", "\\", "|", "/")
252      SPINNER_ARROW: tuple[str, ...] = ("←", "↖", "↑", "↗", "→", "↘", "↓", "↙")
253  
254      # Pulsing circle spinner for structured elements (tools, skills, subagents)
255      # Uses ANSI 256-color codes to create a smooth brightness pulse effect
256      # Grayscale values: 232 (darkest) to 255 (brightest)
257      SPINNER_PULSE_CIRCLE: tuple[str, ...] = (
258          # Fade in (dim to bright)
259          "\033[38;5;240m●\033[0m",  # dim
260          "\033[38;5;243m●\033[0m",
261          "\033[38;5;246m●\033[0m",
262          "\033[38;5;249m●\033[0m",
263          "\033[38;5;252m●\033[0m",
264          "\033[38;5;255m●\033[0m",  # bright
265          # Fade out (bright to dim)
266          "\033[38;5;252m●\033[0m",
267          "\033[38;5;249m●\033[0m",
268          "\033[38;5;246m●\033[0m",
269          "\033[38;5;243m●\033[0m",
270      )
271  
272  
273  # =============================================================================
274  # API Constants
275  # =============================================================================
276  
277  # Default polling interval for HTTP client
278  DEFAULT_POLL_INTERVAL: float = 2.0
279  
280  # HTTP request timeout
281  DEFAULT_HTTP_TIMEOUT: int = 30
282  
283  
284  # =============================================================================
285  # Tool Display Formatting
286  # =============================================================================
287  
288  # Grid layout settings for tool display
289  TOOL_GRID_COLUMNS: int = 4
290  TOOL_GRID_COLUMN_WIDTH: int = 18
291  
292  # JSON preview settings
293  JSON_PREVIEW_MAX_LINES: int = 10
294  JSON_PREVIEW_MAX_LINE_LENGTH: int = 80
295  
296  # Todo plan display settings
297  TODO_PLAN_INDENT: int = 6
298  TODO_CONTENT_MAX_LENGTH: int = 55