brain.logging — Логирование и наблюдаемость¶

Структурированное логирование, дайджесты, трейсинг рассуждений. Аналог метакогниции.

BrainLogger¶

Структурированный логгер с TTL/LRU индексами, ротацией файлов и категорийными потоками.

BrainLogger ¶

BrainLogger(log_dir: str = 'brain/data/logs', min_level: str = 'DEBUG', max_size_mb: float = 100.0, echo_stdout: bool = False)

Потокобезопасный JSONL-логгер для всех модулей мозга.

Параметры

log_dir — директория для файлов логов (создаётся автоматически) min_level — минимальный уровень логирования (DEBUG/INFO/WARN/ERROR/CRITICAL) max_size_mb — максимальный размер brain.jsonl до ротации (МБ) echo_stdout — дублировать ли записи в stdout (для dev-режима)

log ¶

log(level: str, module: str, event: str, *, session_id: str = '', cycle_id: str = '', trace_id: str = '', input_ref: Optional[List[str]] = None, memory_refs: Optional[List[str]] = None, state: Optional[Dict[str, Any]] = None, decision: Optional[Dict[str, Any]] = None, latency_ms: Optional[float] = None, notes: str = '', **extra: Any) -> None

Записать событие в JSONL.

DigestGenerator¶

Генерация периодических дайджестов активности системы.

DigestGenerator ¶

DigestGenerator(digest_dir: str = 'brain/data/logs/digests')

Генератор человекочитаемых дайджестов по когнитивным циклам.

Параметры

digest_dir — директория для файлов дайджестов

generate_session_digest ¶

generate_session_digest(session_id: str, cycles: List[CycleInfo]) -> str

Сгенерировать сводный дайджест по всей сессии.

Параметры

session_id — ID сессии cycles — список CycleInfo всех циклов сессии

TraceBuilder¶

Построение и восстановление цепочки причинности по trace_id.

TraceBuilder ¶

TraceBuilder()

Построитель цепочки причинности для когнитивных решений.

Использование

builder = TraceBuilder()

В начале цикла:¶

builder.start_trace(trace_id, session_id, cycle_id)

В каждом модуле:¶

builder.add_step(trace_id, module="planner", action="goal_created", confidence=1.0, details={"goal": "answer_question"}) builder.add_input_ref(trace_id, ref_type="user_input", ref_id="msg_3") builder.add_memory_ref(trace_id, ref_type="semantic", ref_id="нейрон", note="conf=0.87")

В конце цикла:¶

chain = builder.reconstruct(trace_id) print(builder.to_human_readable(chain))

Очистить завершённый trace:¶

builder.finish_trace(trace_id)

add_step ¶

add_step(trace_id: str, module: str, action: str, confidence: float = 0.0, details: Optional[Dict[str, Any]] = None, refs: Optional[List[TraceRef]] = None) -> None

Добавить шаг reasoning/decision в trace.

start_trace ¶

start_trace(trace_id: str, session_id: str = '', cycle_id: str = '') -> None

Начать новый trace. Если уже существует — сбросить.

finish_trace ¶

finish_trace(trace_id: str) -> Optional[TraceChain]

Завершить trace: построить TraceChain, сохранить в кэш, удалить аккумулятор. Возвращает готовую TraceChain или None если trace не найден.

reconstruct ¶

reconstruct(trace_id: str) -> Optional[TraceChain]

Восстановить TraceChain по trace_id.

Сначала ищет в активных аккумуляторах, затем в кэше завершённых.

reconstruct_from_logger ¶

reconstruct_from_logger(trace_id: str, logger: 'BrainLogger') -> TraceChain

Восстановить TraceChain из событий BrainLogger по trace_id.

Используется для post-hoc анализа когда TraceBuilder не был активен.

to_human_readable ¶

to_human_readable(chain: TraceChain) -> str

Форматировать TraceChain в читаемый текст.