Release Notes - v0.2.6

Release Notes - v0.2.6

🎯 What's New

Enhanced Event Stream API

New event stream mode that gives you complete visibility into tool call execution with type-safe event handling.

What's New: Added event=True parameter to asend() method to enable detailed event stream with full tool call observability.

Complete Tool Call Lifecycle:

from chak.message import MessageChunk, ToolCallStartEvent, ToolCallSuccessEvent, ToolCallErrorEvent

# Use event=True to get detailed events
tool_start_times = {}
async for event in await conv.asend("Calculate 15 + 27", event=True):
    match event:
        case ToolCallStartEvent(tool_name=name, arguments=args, call_id=cid, timestamp=ts):
            tool_start_times[cid] = ts
            print(f"🔧 Calling: {name} with {args}")
        
        case ToolCallSuccessEvent(tool_name=name, call_id=cid, result=res, timestamp=ts):
            duration = ts - tool_start_times.get(cid, ts)
            print(f"✅ Result: {name} -> {res}")
            print(f"   ⏱️  Duration: {duration:.3f}s")
        
        case ToolCallErrorEvent(tool_name=name, call_id=cid, error=err, timestamp=ts):
            duration = ts - tool_start_times.get(cid, ts)
            print(f"❌ Failed: {name} - {err}")
            print(f"   ⏱️  Duration: {duration:.3f}s")
        
        case MessageChunk(content=text, is_final=final, metadata=meta, final_message=msg):
            print(text, end="", flush=True)
            if final and meta:
                print(f"\nTokens used: {meta.get('usage')}")

Key Features:

• 🎯 Clear success/failure handling - ToolCallSuccessEvent and ToolCallErrorEvent for explicit tool results
• 📊 Rich metadata access - Get metadata and final_message from MessageChunk
• 🔗 Complete call tracking - Use call_id to track each tool call from start to finish
• ⏱️ Performance monitoring - Each event includes timestamp to measure tool execution time
• 🛡️ Type-safe - Distinct event types for better pattern matching

📚 Learn More

Check out examples/event_stream_chat_demo.py for a complete working example.

💡 Usage Tips

Import the event types:

from chak.message import MessageChunk, ToolCallStartEvent, ToolCallSuccessEvent, ToolCallErrorEvent

Handle events with match-case:

async for event in await conv.asend(message, event=True):
    match event:
        case MessageChunk(content=text, is_final=final):
            print(text, end="")
            # Access metadata and final_message when needed
        
        case ToolCallSuccessEvent(tool_name=name, result=res):
            print(f"✅ {name}: {res}")
        
        case ToolCallErrorEvent(tool_name=name, error=err):
            print(f"❌ {name}: {err}")

Or use isinstance (for Python < 3.10):

async for event in await conv.asend(message, event=True):
    if isinstance(event, MessageChunk):
        print(event.content, end="")
        if event.is_final and event.metadata:
            print(f"\nTokens: {event.metadata.get('usage')}")
    
    elif isinstance(event, ToolCallSuccessEvent):
        print(f"✅ {event.tool_name}: {event.result}")
    
    elif isinstance(event, ToolCallErrorEvent):
        print(f"❌ {event.tool_name}: {event.error}")