Logging & Events¶

HBIA includes a structured logging system designed for both human debugging and AI consumption.

AILogger¶

The AILogger produces structured JSON log entries for every significant event during execution.

from honey_badgeria.logging import AILogger, EventType

logger = AILogger("hbia")

Convenience Methods¶

logger.vertex_started("my_vertex")
logger.vertex_completed("my_vertex", result_keys=["output1", "output2"])
logger.flow_started("my_flow")
logger.flow_completed("my_flow")

Manual Logging¶

logger.log(EventType.ATOMIC_GROUP_ENTERED, {
    "group": "payment",
    "vertices": ["validate", "charge", "confirm"],
})

Query Events¶

events = logger.get_events()     # list[dict]
logger.clear()                   # Reset event history

Event Types¶

Predefined event constants from honey_badgeria.logging.event_types:

Vertex Events¶

Event	When
`VERTEX_STARTED`	A vertex begins execution
`VERTEX_COMPLETED`	A vertex finishes successfully

Flow Events¶

Event	When
`FLOW_STARTED`	A flow begins execution
`FLOW_COMPLETED`	A flow finishes

Atomic Events¶

Event	When
`ATOMIC_SNAPSHOT_SAVED`	Pre-execution snapshot captured
`ATOMIC_GROUP_ENTERED`	Entering an atomic group
`ATOMIC_COMMITTED`	Atomic group committed successfully
`ATOMIC_ROLLED_BACK`	Atomic group rolled back on failure

SAGA Events¶

Event	When
`SAGA_STARTED`	SAGA execution begins
`SAGA_STEP_STARTED`	A SAGA step begins
`SAGA_STEP_COMPLETED`	A SAGA step succeeds
`SAGA_STEP_FAILED`	A SAGA step fails
`SAGA_COMPLETED`	SAGA execution finishes

Integration with Execution¶

The GraphExecutor and SagaCoordinator use AILogger internally. Events are recorded automatically during execution:

from honey_badgeria.logging import AILogger

logger = AILogger("hbia")

result = run_flow(graph, handlers={...}, initial_data={...})

# After execution, all events are available
for event in logger.get_events():
    print(f"[{event['type']}] {event['data']}")

Log Format¶

Each log entry is a structured dictionary:

{
    "type": "VERTEX_COMPLETED",
    "data": {
        "vertex": "fetch_user",
        "result_keys": ["id", "name", "email"],
    },
    "timestamp": "2026-04-03T12:00:00Z",
}

This format is designed for both human readability and machine parsing. AI agents can query the event log to understand what happened during execution.