Logging

kanoa provides a built-in logging system optimized for Jupyter notebooks. When verbose mode is enabled, log messages appear in styled containers that update in place — avoiding the clutter of multiple output boxes.

Quick Start

import kanoa

# Enable verbose logging
kanoa.options.verbose = 1  # INFO level
kanoa.options.verbose = 2  # DEBUG level (more detailed)

When you call interpret(), log messages automatically stream into a single lavender “kanoa” container:

from kanoa import AnalyticsInterpreter

interpreter = AnalyticsInterpreter(backend="gemini", verbose=True)
result = interpreter.interpret(fig=my_figure, display_result=True)

Log Levels

kanoa supports four log levels with visual differentiation via text opacity:

Level	Text Opacity	Use Case
DEBUG	50%	Detailed diagnostics (faded)
INFO	85%	General progress
WARNING	95%	Important notices
ERROR	100%	Failures (full intensity)

User Log Functions

Import from kanoa.utils:

from kanoa.utils import log_debug, log_info, log_warning, log_error

Each function accepts:

• message (str): The log message

• title (str, optional): A bolded title prefix for the message

• context (dict, optional): Structured metadata

log_info("Processing complete", title="Status")
log_warning("Rate limit approaching", context={"remaining": 10})
log_error("API call failed", title="Error")

User log calls outside of a log_stream() context are collected into an auto-created container with a gray background (one per cell execution).

Custom Log Streams

Use log_stream() to group related messages into a single container:

from kanoa.utils import log_stream, log_info, log_warning

with log_stream(title="Data Pipeline"):
    log_info("Step 1: Loading data...")
    log_warning("Found 5 missing values", title="Data Quality")
    log_info("Step 2: Transformations complete")

This produces a single styled container with all messages, rather than separate boxes for each log call.

Custom Colors and Opacity

Override the default gray background with RGB tuples and opacity:

# Ocean blue theme with custom opacity
with log_stream(title="Ocean Theme", bg_color=(2, 62, 138), bg_opacity=0.2):
    log_info("Using ocean blue colors")

# Sunset orange theme
with log_stream(title="Sunset Theme", bg_color=(230, 115, 0), bg_opacity=0.15):
    log_info("Using sunset orange colors")

Text color inherits from your notebook/editor theme and is not customizable.

Logging Rich Objects

Use log_object() to render DataFrames and other objects as styled tables:

from kanoa.utils import log_stream, log_info, log_object
import pandas as pd

df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})

with log_stream(title="Data Analysis"):
    log_info("Loading dataset...")
    log_object(df, label="Dataset Preview")
    log_info("Analysis complete")

Configuration Options

Default Stream Title

By default, user logs go to an untitled stream. Change this globally:

kanoa.options.default_log_stream = "My App"  # Custom title
kanoa.options.default_log_stream = False     # Disable auto-streaming

Background Colors

There are two background color settings:

• user_log_bg_color — For user log_*() calls and log_stream() (default: gray)

• internal_log_bg_color — For kanoa internal logs during interpret() (default: lavender)

kanoa.options.user_log_bg_color = (100, 149, 237)      # Cornflower blue
kanoa.options.internal_log_bg_color = (138, 43, 226)   # Purple

User Log Opacity

Adjust the background opacity for user logs (default: 0.04, very translucent):

kanoa.options.user_log_opacity = 0.12  # More visible

Console Mode

Outside of Jupyter notebooks, logs print progressively to the console with the same grouping behavior — no special styling, just clean text output.

Per-Cell Behavior

In notebooks, each cell execution gets its own log container. Running multiple cells produces separate containers:

# Cell 1
with log_stream(title="Step 1"):
    log_info("Message A")
    log_info("Message B")

# Cell 2
with log_stream(title="Step 2"):
    log_info("Message C")

You’ll see two separate boxes — one per cell — rather than all messages merging into a single container across cells.

Disabling Logging

Set verbose to 0 to disable all verbose output:

kanoa.options.verbose = 0

Disable just the auto-streaming for user logs:

kanoa.options.default_log_stream = False