Named verbosity channels: selective output with -v CHANNEL

[djdarcy]

Named verbosity channels: selective output with -v CHANNEL

Problem

The current verbosity system (-v, -vv, -vvv) is a single numeric dial — turning it up reveals everything at that level. Users can't selectively enable one category of verbose output without getting all the others.

Motivating example: When running a comparison search, the output only shows variable bindings:

C:\code\Prime-Square-Sum>prime-square-sum.py --expr "for_any tri(n) == trisum(m)" --max n:50 --max m:50
Found: m=3, n=2
Found: m=4, n=2
Found: m=5, n=2
Found: m=10, n=36

Users often want to see what values satisfied the comparison — e.g., tri(2) = 3 == trisum(3) = 3 — to understand the relationship, not just the variable assignments. But there's no way to get this without enabling -v, which also dumps expression parsing, variable enumeration, bounds, timing, and other noise.

Proposed solution

Extend the verbosity system to support named channels alongside numeric levels:

# Numeric levels (existing behavior, unchanged)
-v              # level 1 — expression, variables, bounds, timing
-vv             # level 2 — config, algorithm selection
-vvv            # level 3 — debug

# Named channels (new)
-v vals          # show computed LHS/RHS values on match output
-v parse         # show parse tree details
-v iter          # show iteration progress
-v timing        # show timing breakdowns
-v config        # show configuration resolution
-v algorithm     # show algorithm selection details
-v hint          # show all hints regardless of context

# Combined: numeric level + specific channels
-vv vals         # level 2 + vals channel
-v vals timing   # level 1 + vals + timing channels

Channel activation rules

A message with emit(level, msg, channel='foo') displays if ANY of:

1. Numeric verbosity >= level (existing behavior)
2. Channel 'foo' is explicitly enabled via -v foo
3. --quiet is NOT set

This means -v vals at verbosity level 0 would show ONLY the vals channel output (plus level-0 messages), without triggering all the level-1 noise.

First use case: vals channel

The vals channel would display computed LHS and RHS values alongside match output:

# Default (no -v)
Found: m=3, n=2

# With -v vals
Found: m=3, n=2 → tri(2) = 3 == trisum(3) = 3

# With -v vals (does_exist, single match)
Found: n=7 → primesum(7,2) = 666 == 666

Implementation for vals: find_matches() would need to evaluate LHS and RHS independently (currently it only evaluates the full comparison as a boolean) and include them in the yield dict (e.g., __lhs_value__, __rhs_value__). format_match() would then check if vals channel is enabled and append the value display.

Current channel inventory

These channels already exist internally (used in emit() calls) but are not user-accessible:

Channel	Current usage	Level
parse	Expression string display	1
iter	Variables, bounds	1
timing	Match count, elapsed time	1
config	Config loading, sieve settings, silence hint	1-2
algorithm	Algorithm selection, memory limits	2
hint	Contextual tips and suggestions	0
progress	Match count during long runs	1
general	Default/uncategorized	varies
vals	NEW — computed LHS/RHS values	1

CLI design

The -v flag currently uses action='count'. To support named channels, parsing would need to change:

# Option A: Extend -v to accept optional channel names
parser.add_argument('-v', '--verbose', nargs='*', action='append')
# -v → [None]  (level 1)
# -v -v → [None, None]  (level 2)
# -v vals → ['vals']  (level 0 + vals channel)
# -vv vals → parsed as level 2 + vals

# Option B: Separate flag for channels
parser.add_argument('-v', '--verbose', action='count', default=0)
parser.add_argument('--show', action='append', metavar='CHANNEL')
# -v --show vals
# --show vals --show timing

# Option C: Combined syntax with colon
parser.add_argument('-v', '--verbose', action='append')
# -v         (level 1)
# -v:vals    (enable vals channel)
# -vv:vals   (level 2 + vals)

Option A is cleanest for users but requires custom argument parsing. Option B is simplest to implement. Option C mirrors common logging conventions.

OutputManager changes

class OutputManager:
    def __init__(self, verbosity=0, quiet=False, channels=None, file=None):
        self.verbosity = verbosity
        self.quiet = quiet
        self.enabled_channels = set(channels or [])
        # ...

    def emit(self, level, message, *, channel='general', **kwargs):
        if self.quiet:
            return
        if self.verbosity < level and channel not in self.enabled_channels:
            return
        text = message.format(**kwargs) if kwargs else message
        print(text, file=self.file)

Documentation

This feature warrants its own documentation page (docs/verbosity.md or docs/output-channels.md) explaining:

• The numeric level system and what each level shows
• Available named channels and what they control
• Combined usage patterns
• Examples for common workflows (debugging, value inspection, performance analysis)
• How channels interact with --quiet and --format json

Acceptance criteria

• OutputManager supports enabled_channels set
• emit() checks channel membership as alternative to numeric level
• CLI flag syntax chosen and implemented (Option A, B, or C)
• vals channel implemented as first named channel
  • find_matches() yields __lhs_value__ and __rhs_value__ for comparison matches
  • format_match() appends value display when vals channel is active
• Existing numeric -v/-vv/-vvv behavior unchanged
• Documentation page for output channels
• Tests for channel-based filtering

Related issues

• Multi-level verbosity system (-v, -vv, -vvv) #31 Multi-level verbosity system (closed — implemented the numeric levels)
• Structured hint and help system for CLI guidance #57 Structured hint and help system (hints are a channel category)
• Output destination routing (--output file/clip/stdout/all) and pager research #59 Output destination routing (orthogonal — where output goes vs what output is shown)
• Enhanced JSON output with expression context #35 Enhanced JSON output (format-specific channel behavior)

Analysis

See 2026-02-10__16-08-44__full-postmortem_issue-63-dynamic-cli-help-defaults.md for the session context where this feature was identified.

[djdarcy]

Performance note: avoiding redundant evaluation for vals channel

The vals channel would show computed LHS and RHS values on match output. Since find_matches() currently evaluates the full comparison as a single boolean (evaluator.evaluate(expr.body, context) → True/False), displaying the individual side values requires evaluating them again separately.

The good news: this only happens for matching combinations, not all combinations. If 5,000 combinations yield 4 matches, we'd only re-evaluate 4 times — negligible.

However, for for_any searches with many matches (e.g., thousands of results), the double evaluation adds up. And for expensive functions like primesum(n, 2) without caching (#19), each redundant call triggers a fresh prime sieve.

Optimization strategies

1. Evaluate-and-capture pattern: Restructure the evaluator so that comparison evaluation captures both side values as it goes. Instead of just returning True/False, return a result object like MatchResult(matched=True, lhs_value=666, rhs_value=666). This eliminates double evaluation entirely — the values are captured during the first (and only) evaluation pass.

2. Lazy evaluation on format: Only evaluate LHS/RHS at format time (in format_match()), but this requires passing the AST and evaluator through, which couples formatting to evaluation.

3. Conditional re-evaluation: Only evaluate LHS/RHS when the vals channel is enabled. If vals isn't active, skip entirely — zero overhead for the default path. Combined with Performance optimization: Python 3 + primesieve + CuPy (GPU) #1, this means the capture overhead only exists when the user explicitly asks for it.

4. Expression-level caching (longer term): Memoize function calls within a single evaluation context. If primesum(7, 2) is computed for the comparison check, the same call during value capture returns the cached result. This overlaps with Issue Multi-sequence cache architecture for expression optimization (v0.9.0) #19 (cumulative cache) and Constant expression hoisting for iteration loops #60 (constant expression hoisting).

Recommendation

Strategy 1 (evaluate-and-capture) is the cleanest — it changes the evaluator's internal return path for comparisons without affecting the external API. The match dict would include __lhs_value__ and __rhs_value__ keys only when vals channel is active, keeping the default path unchanged.

Strategy 3 (conditional) should be applied regardless — never compute values nobody asked to see.

[djdarcy]

Design Update: THAC0 Unified Verbosity + Channel System

Issue #65 has evolved significantly during design planning. The original scope (add --show flag) has expanded into a foundational library design for log_lib/ — a reusable output management library targeting DazzleLib.

Key Design Decisions (see 2026-02-13__16-15-08__dev-workflow_issue65-named-verbosity-channels.md)

THAC0 Verbosity Model: Single signed integer axis replacing separate verbosity/quiet systems.

• -v increments, -q decrements, they compose: -vv -q = 1
• Emit rule: message.level <= threshold
• Per-channel overrides: --show timing:2 pins timing to level 2

Channel Spec Syntax: CHANNEL:LEVEL:DEST:LOCATION:FORMAT (compact, positional)

• Plus expanded flags: --chan-lvl, --chan-fmt, --chan-dest (like --iter-* pattern)
• Bare --show lists available channels

Library Structure: utils/log_lib/ (new) + utils/help_lib/ (ported from modified_datetime_fix)

Sub-Areas to Explore During Implementation

1. Hint context + THAC0 interaction: The hint system has context filtering ('error', 'result', 'verbose') which is orthogonal to the THAC0 level. How do these compose? Both should apply, but the exact interaction needs implementation-time thought.

2. error() as emit(-3, ...): In the unified model, error() becomes a regular emit call at level -3. This means per-channel overrides could theoretically silence errors (--show error:-4). Is this the right behavior, or should errors have a floor?

3. stderr as default destination, not rule: The current "everything to stderr" design was pre-channel. With per-channel destinations, each channel gets its own default destination. vals defaults to stdout (annotates match output), others default to stderr.

4. Bare --show argparse interaction: action='append' doesn't natively support nargs='?' for listing channels when no argument given. Need to decide: separate --list-channels flag, or post-parse detection.

Consulted with Gemini 2.5 Pro

Design validated on all 7 points. New suggestions for DazzleLib roadmap:

• Thread safety (locking for _shown_hints)
• Contextual indentation (with out.indent():)
• Rich/colored output as optional dependency
• Bidirectional logging bridge handler
• Buffered destinations for high-frequency emit

Analysis

See 2026-02-13__16-15-08__dev-workflow_issue65-named-verbosity-channels.md (9 addendums) and 2026-02-13__18-32-00__DISCUSS_Rnd2_FINAL_ASSESSMENT_thac0-channel-system-design.md for detailed analysis.