Skip to content

Implement structured logging across VRE #39

@anormang1992

Description

@anormang1992

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 SKIPPED but 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 logging module 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 NullHandler on the top-level vre logger (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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions