Add LLM routing metadata to generation observability

Author: alessiodevoto

examples/README.md

@@ -567,7 +567,7 @@ class DataAgent(Agent, llm=llm):
 
 ### LLM cascading resolution
 
-Configure LLMs at any granularity — class default, method override, instance override — for cost/latency optimization, A/B testing, or gradual rollouts.
+Configure LLMs at any granularity — class default, method override, instance override, or per-call override — for cost/latency optimization, A/B testing, or gradual rollouts.
 
 ```python
 class MyAgent(Agent, llm=default_llm):              # 1. class default

src/nooa/runtime/actor.py

@@ -62,6 +62,8 @@
 
 logger = logging.getLogger(__name__)
 
+_MISSING = object()
+
 
 @contextmanager
 def _harness_metrics_lifecycle(should_trace: bool):
@@ -401,6 +403,12 @@ def _strip_blocked_modules(
     "current_method", default=None
 )
 _current_llm_var: contextvars.ContextVar[Any] = contextvars.ContextVar("current_llm", default=None)
+_current_llm_model_name_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_llm_model_name", default=None
+)
+_current_llm_selection_source_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_llm_selection_source", default=None
+)
 
 # Context variable for the resolved truncation config for the current generation call.
 # Set by _execute_with_generation() so that method-level @strategy(truncation=...)
@@ -1953,6 +1961,14 @@ async def execute_nested(
         if hasattr(strategy, "prefill") and getattr(strategy, "prefill") is not None:  # noqa: B009
             strategy_kwargs["has_prefill"] = True
 
+        llm_model_name = _current_llm_model_name_var.get()
+        llm_selection_source = _current_llm_selection_source_var.get()
+        llm_kwargs = {}
+        if llm_model_name is not None:
+            llm_kwargs["llm.model_name"] = llm_model_name
+        if llm_selection_source is not None:
+            llm_kwargs["llm.selection_source"] = llm_selection_source
+
         # Call generation hooks (skip for non-traceable strategies like TemplateStrategy)
         should_trace = strategy.traceable
         hook_context = None
@@ -1965,6 +1981,7 @@ async def execute_nested(
                 generation_id=generation_id,
                 parent_generation_id=parent_generation_id,
                 agent_call_id=self._agent_call_id,
+                **llm_kwargs,
                 **strategy_kwargs,  # Add strategy config parameters
             )
 
@@ -2530,13 +2547,18 @@ async def _execute_with_generation(
         method_name: str,
     ) -> Any:
         """Execute a method that needs LLM generation."""
+        base_method = getattr(method, "__func__", method)
+        try:
+            has_user_llm_param = "llm" in inspect.signature(method).parameters
+        except (TypeError, ValueError):
+            has_user_llm_param = False
+
         # Extract framework parameters (don't pass to generated method)
         call_strategy = kwargs.pop("_strategy", None)
-        call_llm = kwargs.pop("llm", None)
+        call_llm = kwargs.pop("llm", _MISSING) if not has_user_llm_param else _MISSING
         call_session_locals = kwargs.pop("_session_locals", None)
 
         # Get strategy with priority: call-level > decorator > default
-        base_method = getattr(method, "__func__", method)
         decorator_strategy = getattr(base_method, "_plan_strategy", None)
 
         # DEBUG: Log strategy retrieval for nested method debugging
@@ -2561,17 +2583,21 @@ async def _execute_with_generation(
         # A @strategy(llm=...) value may be a callable resolved against the agent
         # instance; only invoke it when it would actually be used, so a call-level
         # override doesn't trigger someone else's resolver side effects.
-        if call_llm is not None:
+        plan_llm = getattr(base_method, "_plan_llm", None)
+        if call_llm is not _MISSING and call_llm is not None:
             llm_client = call_llm
-        else:
-            plan_llm = getattr(base_method, "_plan_llm", None)
-            if plan_llm is not None:
-                from nooa.method_llm import resolve_method_llm
+            llm_selection_source = "call_site"
+        elif plan_llm is not None:
+            from nooa.method_llm import resolve_method_llm
 
-                plan_llm = resolve_method_llm(plan_llm, self.agent, method_name)
-            llm_client = plan_llm or getattr(self.agent, "_llm", None)
+            llm_client = resolve_method_llm(plan_llm, self.agent, method_name)
+            llm_selection_source = "decorator"
+        else:
+            llm_client = getattr(self.agent, "_llm", None)
+            llm_selection_source = "agent_default"
         if llm_client is None:
             raise RuntimeError(f"No LLM client available for {method_name}")
+        llm_model_name = getattr(llm_client, "model", "") or ""
 
         # Resolve truncation config: method-level @strategy(truncation=...) > agent-level
         method_truncation = getattr(base_method, "_strategy_truncation", None)
@@ -2615,6 +2641,10 @@ async def _execute_with_generation(
                 generation_id=generation_id,
                 parent_generation_id=parent_generation_id,
                 agent_call_id=self._agent_call_id,
+                **{
+                    "llm.model_name": llm_model_name,
+                    "llm.selection_source": llm_selection_source,
+                },
                 **strategy_kwargs,  # Add strategy config parameters
             )
 
@@ -2709,6 +2739,10 @@ async def _execute_with_generation(
                 call_token = _current_call_var.set(call)
                 method_token = _current_method_var.set(method)
                 llm_token = _current_llm_var.set(llm_client)
+                llm_model_name_token = _current_llm_model_name_var.set(llm_model_name)
+                llm_selection_source_token = _current_llm_selection_source_var.set(
+                    llm_selection_source
+                )
                 truncation_token = _current_truncation_config_var.set(resolved_truncation)
                 event_format_token = _current_event_format_var.set(
                     resolved_truncation.event_format.model_dump()
@@ -2749,6 +2783,8 @@ async def _execute_with_generation(
                     _current_call_var.reset(call_token)
                     _current_method_var.reset(method_token)
                     _current_llm_var.reset(llm_token)
+                    _current_llm_model_name_var.reset(llm_model_name_token)
+                    _current_llm_selection_source_var.reset(llm_selection_source_token)
                     _current_truncation_config_var.reset(truncation_token)
                     _current_event_format_var.reset(event_format_token)
                     _decorator_context_var.reset(decorator_ctx_token)

src/nooa/runtime/method_wrapper.py

@@ -11,6 +11,7 @@
 """
 
 import asyncio
+import inspect
 import logging
 from collections.abc import Callable
 from functools import wraps
@@ -127,9 +128,15 @@ async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
             if hasattr(self, "runtime"):
                 _fw_kwargs = {
                     _name: kwargs.pop(_name)
-                    for _name in ("_session_locals", "_strategy", "llm")
+                    for _name in ("_session_locals", "_strategy")
                     if _name in kwargs
                 }
+                try:
+                    _has_user_llm_param = "llm" in inspect.signature(original_func).parameters
+                except (TypeError, ValueError):
+                    _has_user_llm_param = False
+                if not _has_user_llm_param and "llm" in kwargs:
+                    _fw_kwargs["llm"] = kwargs.pop("llm")
             try:
                 ArgumentValidator().validate(original_func, args, kwargs, _tc)
             finally: