-
Notifications
You must be signed in to change notification settings - Fork 1
Closed
Description
Summary
Introduce a consistent logging framework across the VRE codebase to surface diagnostic information — warnings, state transitions, and non-fatal events — without changing public interfaces.
Problem Statement
VRE currently has no logging. Diagnostic information is either silently swallowed or surfaced only through return values and exceptions. This means:
- Non-fatal events (e.g. cycle detection skipping a reachability candidate in the learning loop) produce no visible signal — the caller sees
SKIPPEDbut has no way to know why - Engine internals (grounding decisions, depth gating, policy evaluation) are opaque during development and debugging
- Integrators have no way to observe VRE's internal decision-making without instrumenting every call site
The immediate trigger is #33 (cycle detection): when save_primitive raises CyclicRelationshipError and the learning engine catches it, the descriptive error message is swallowed. A logging.warning would surface the reason, but introducing logging ad hoc in one exception handler sets a precedent without a deliberate framework.
Proposed Solution
Adopt Python's standard logging module with a consistent pattern:
- Module-level loggers:
logger = logging.getLogger(__name__)in each module - Log levels aligned to event significance:
DEBUG: internal state transitions (depth gating decisions, BFS traversal steps, template creation)INFO: meaningful operations (grounding checks, learning loop iterations, policy evaluations)WARNING: non-fatal issues that affect behavior (cycle detection skips, missing provenance, unresolved concepts)ERROR: failures that propagate (persistence errors, validation failures)
- Structured messages with enough context to diagnose without reading code
VRE Design Alignment
- Inspectability: CLAUDE.md Section 8 lists inspectability as a core value. Logging makes the engine's reasoning visible beyond the structured return types.
- No contract changes: Logging is a side effect — it does not alter grounding, policy, or learning behavior. All existing interfaces remain unchanged.
- Minimal footprint: Python's
loggingmodule is stdlib — no new dependencies.
Acceptance Criteria
- Module-level loggers in core engine modules (
grounding/engine.py,learning/engine.py,policy/gate.py,core/graph.py) - Cycle detection skip in learning engine logged at WARNING with the error message from
CyclicRelationshipError - Grounding decisions logged at DEBUG/INFO
- No logging configuration imposed — integrators control handlers and levels
- Existing tests unaffected
Open Questions
- Should VRE configure a
NullHandleron the top-levelvrelogger (standard library best practice for libraries)? - Should log messages include structured data (primitive IDs, gap types) or just human-readable strings?
- Should the trace/policy callback hooks remain the primary observability mechanism, with logging as a secondary channel?
Dependencies
- Add validation on edge placement to detect possible cyclical relationships #33 (Cycle detection) — the immediate motivation for the first logging call site
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Projects
Status
Done