Add Multi-File Tracing Support with Bug Fixes

[kiranscaria]

Add Multi-File Tracing Support with Bug Fixes

Summary

This PR introduces support for tracing multi-file agentic applications while maintaining full backward compatibility with existing tracer implementations. The new system enables distributed tracing across multiple files/modules and provides flexible initialization patterns.

Key Changes

• ✨ Added support for tracing across multiple files/modules
• ♻️ Maintained backward compatibility with existing tracer instances
• 🛠 Introduced new initialization pattern with init_tracing()
• 📚 Added comprehensive example (travel_agent) demonstrating new functionality
• 🐛 Fixed nested agents cost/usage calculations
• 🐛 Corrected workflow key

Before & After

Previous Implementation (v1)

catalyst = RagaAICatalyst(...)
tracer = Tracer(...)  # Single file usage only

New Implementation (v2)

# Initialize custom instances once
init_tracing(tracer=tracer, catalyst=catalyst)  # Enables multi-file tracing

# Use tracing decorators across multiple files
@trace_tool(name="weather_fetcher")
def get_weather(location): ...

@trace_agent(name="master_agent")
def main_workflow(): ...

New Syntax Overview

Step 1: Central Initialization

from ragaai_catalyst import RagaAICatalyst, Tracer, init_tracing

# Create custom configured instances
catalyst = RagaAICatalyst(
    access_key="CUSTOM_KEY",
    secret_key="CUSTOM_SECRET",
    base_url="CUSTOM_ENDPOINT"
)

tracer = Tracer(
    project_name="DebugProject",
    dataset_name="Staging",
    tracer_type="Experimental"
)

# Register instances globally
init_tracing(tracer=tracer, catalyst=catalyst)

Step 2: Distributed Tracing

# File: weather_service.py
from ragaai_catalyst import trace_tool

@trace_tool(name="weather_fetcher")
def get_weather(location):
    # Implementation

# File: workflow_manager.py
from ragaai_catalyst import trace_agent

@trace_agent(name="master_agent")
def main_workflow():
    # Cross-file workflow

Step 3: Execution Control

# Context manager approach
with tracer:
    execute_workflow()

# Explicit start/stop alternative
tracer.start()
try:
    execute_workflow()
finally:
    tracer.stop()

Example Implementation

A complete implementation example is available in the new travel_agent example demonstrating:

• Multi-service tracing
• Cross-file instrumentation
• Nested workflow tracking

Backward Compatibility

All existing implementations will continue working unchanged:

# Legacy code still works
catalyst = RagaAICatalyst(...)
tracer = Tracer(...)
# Existing tracer usage patterns remain valid

Important Notes

• Existing tracer instances can be upgraded to multi-file tracing by adding init_tracing()
• New decorators (@trace_tool, @trace_agent) work across files after initialization
• Tracer lifecycle management remains consistent with previous versions