feat(evaluators): 17516 request payload contract (#271)

## Summary

- Add an optional `tools` argument to `@control` for static definitions
or a dynamic provider. Tool definitions are included only on LLM steps;
omitting `tools` preserves existing decorator behavior.
- Build canonical Galileo Core records from the complete Agent Control
`Step` tree. `Trace.children` map to spans, `Session.children` map to
traces, and tool/retriever children map to nested spans.
- Use `Step.children` as the only source of execution hierarchy. Reject
hierarchy fields in `Step.context` while preserving ordinary metadata.
- Have Luna send the legacy `inputs` together with a canonical `record`
when a supported runtime `Step` is available. Selector-selected values
are passed into the shared records factory; the existing
`ScorerInvokeRecord` request model and legacy request shape remain
unchanged.
- Normalize record fields with `galileo-core` models and cover
serialization, request-model validation, and Core-model revalidation in
tests.

## Scope

- User-facing/API changes: optional keyword-only `tools` on `@control`,
accepting static definitions or a `(args, kwargs)` provider; SDK
documentation updated. Existing calls without tools remain compatible.
- Internal changes: recursive Galileo record conversion from
`Step.children`; Luna structured-record dual-write alongside legacy
inputs; field-level normalization and request validation; regression
tests.
- Out of scope: calling Orbit's `execute_scorer`, `tool_calls`,
Agent/Workflow/Control nested spans, framework-specific integrations,
persistence, and changes to Orbit or Luna's public request/response
contracts. The scorer version remains caller-supplied; the client does
not infer one.

## Risk and Rollout

- Risk level: moderate. Luna requests continue to include legacy inputs,
and no database schema changes are included.
- Rollback plan: revert this PR. No data migration is required.

## Testing

- [x] Added or updated tests for `@control` tools, `Step.children`
record trees, context hierarchy rejection, Luna request serialization,
and Galileo Core serialization/revalidation.
- [x] Galileo package test suite: 187 passed using the existing package
virtual environment.
- [x] Ruff, mypy, and `git diff --check` passed for the changed package
files.
- [ ] Repo-wide `make check` could not start because the configured
Artifactory package index returned 403 while resolving `google-re2`.
- [ ] Fresh CI is pending for the updated PR head. The previous run was
against the pre-fix head and reported five Galileo test failures plus a
generated TypeScript client check failure.
- [ ] Manually verified behavior; validation is through automated tests
and code review.

## Checklist

- [x] Issue/spec: SAO-17516 (referenced in the PR title).
- [x] Updated SDK documentation for the decorator API and direct Step
construction.
- [x] Follow-up noted: wiring Luna to Orbit's `execute_scorer` path and
adding `tool_calls` are separate work.

Author: namrataghadi-galileo

evaluators/contrib/galileo/src/agent_control_evaluator_galileo/__init__.py

@@ -32,11 +32,11 @@
 )
 from agent_control_evaluator_galileo.records import (
     GalileoRecord,
+    GalileoRecordNormalizer,
     RecordFactoryError,
     UnsupportedStepTypeError,
     build_galileo_record,
     build_record,
-    record_from_scorer_invoke_record,
     record_from_step,
 )
 
@@ -51,10 +51,10 @@
     "LunaOperator",
     "LUNA_AVAILABLE",
     "GalileoRecord",
+    "GalileoRecordNormalizer",
     "RecordFactoryError",
     "UnsupportedStepTypeError",
     "build_galileo_record",
     "build_record",
-    "record_from_scorer_invoke_record",
     "record_from_step",
 ]

evaluators/contrib/galileo/src/agent_control_evaluator_galileo/luna/client.py

@@ -11,13 +11,14 @@
 from hmac import new as hmac_new
 from json import dumps
 from time import time
-from typing import Literal, cast, get_args
+from typing import Any, Literal, get_args
 from urllib.parse import urlsplit
 
 import httpx
 from agent_control_models import JSONObject, JSONValue, Step
-from pydantic import BaseModel, Field, PrivateAttr, model_validator
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, model_validator
 
+from ..records import UnsupportedStepTypeError, record_from_step
 from .config import ScorerInvokeConfig
 
 logger = logging.getLogger(__name__)
@@ -57,6 +58,7 @@
     "session",
 ]
 SUPPORTED_SCORER_INVOKE_RECORD_TYPES = frozenset(get_args(ScorerInvokeRecordType))
+_MISSING_SELECTED_DATA = object()
 
 
 def _b64url(data: bytes) -> str:
@@ -219,6 +221,8 @@ class ScorerInvokeRecord(BaseModel):
     represented here. Orbit hydrates those fields from trusted server context.
     """
 
+    model_config = ConfigDict(extra="allow")
+
     type: ScorerInvokeRecordType
     name: str | None = None
     input: JSONValue = None
@@ -272,11 +276,13 @@ def to_dict(self) -> JSONObject:
         return request
 
 
-def _orbit_record_from_step(
+def _scorer_invoke_record_from_step(
     step: Step | None,
     *,
     selected_input: JSONValue,
     selected_output: JSONValue,
+    selected_data: Any = _MISSING_SELECTED_DATA,
+    payload_field: str = "input",
 ) -> ScorerInvokeRecord | None:
     """Translate a generic Agent Control step into Orbit's record contract.
 
@@ -297,21 +303,30 @@ def _orbit_record_from_step(
     Returns:
         An Orbit-compatible record, or ``None`` for absent/unsupported steps.
     """
-    if step is None or step.type not in SUPPORTED_SCORER_INVOKE_RECORD_TYPES:
+    if step is None:
         return None
-
-    # The membership check above narrows the runtime value to Orbit's known
-    # discriminator set, but static type checkers cannot infer that relationship.
-    record_type = cast(ScorerInvokeRecordType, step.type)
-    return ScorerInvokeRecord(
-        type=record_type,
-        name=step.name,
-        input=selected_input if selected_input is not None else step.input,
-        output=selected_output if selected_output is not None else step.output,
-        context=step.context,
-        tools=step.tools,
-        dataset_output=step.ground_truth,
-    )
+    try:
+        if selected_data is _MISSING_SELECTED_DATA:
+            galileo_core_record = record_from_step(
+                step,
+                selected_input=selected_input,
+                selected_output=selected_output,
+            )
+        else:
+            galileo_core_record = record_from_step(
+                step,
+                selected_data=selected_data,
+                payload_field=payload_field,
+            )
+    except UnsupportedStepTypeError:
+        return None
+    # record_from_step() returns Galileo Core models (LlmSpan, Trace, etc.). Dumping
+    # and revalidating coerces the model into the Luna request shape while preserving
+    # extra canonical fields that Orbit accepts but ScorerInvokeRecord does not declare.
+    canonical_record = galileo_core_record.model_dump(mode="json", exclude_none=True)
+    if canonical_record.get("type") not in SUPPORTED_SCORER_INVOKE_RECORD_TYPES:
+        return None
+    return ScorerInvokeRecord.model_validate(canonical_record)
 
 
 class ScorerInvokeResponse(BaseModel):
@@ -487,6 +502,8 @@ async def invoke(
         input: JSONValue = None,
         output: JSONValue = None,
         step: Step | None = None,
+        selected_data: Any = _MISSING_SELECTED_DATA,
+        selected_data_payload_field: str = "input",
         execution_context: GalileoExecutionContext | None = None,
         config: ScorerInvokeConfig | JSONObject | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECS,
@@ -502,6 +519,9 @@ async def invoke(
             input: Optional user/system prompt text.
             output: Optional model response text.
             step: Optional complete runtime step used for structured dual-write.
+            selected_data: Raw selector-selected value used to construct the record,
+                preserving its structure independently from serialized legacy inputs.
+            selected_data_payload_field: Record input/output side for scalar selector values.
             execution_context: Optional authenticated Galileo scorer context.
             config: Optional Orbit-supported scorer invocation configuration.
             timeout: Request timeout in seconds.
@@ -531,6 +551,17 @@ async def invoke(
             invoke_config,
             http_timeout_seconds=timeout,
         )
+        record = (
+            _scorer_invoke_record_from_step(
+                step,
+                selected_input=input,
+                selected_output=output,
+                selected_data=selected_data,
+                payload_field=selected_data_payload_field,
+            )
+            if step is not None and scorer_version_id is not None
+            else None
+        )
         request_body = ScorerInvokeRequest(
             scorer_id=scorer_id,
             scorer_version_id=scorer_version_id,
@@ -541,11 +572,7 @@ async def invoke(
                 ground_truth=step.ground_truth if step is not None else None,
                 tools=step.tools if step is not None else None,
             ),
-            record=_orbit_record_from_step(
-                step,
-                selected_input=input,
-                selected_output=output,
-            ),
+            record=record,
             execution_context=execution_context,
             config=invoke_config,
         ).to_dict()

evaluators/contrib/galileo/src/agent_control_evaluator_galileo/luna/config.py

@@ -56,8 +56,8 @@ class LunaEvaluatorConfig(EvaluatorConfig):
 
     Attributes:
         scorer_id: Required scorer identifier for Luna scorer invocation.
-        scorer_version_id: Deprecated optional compatibility identifier. Orbit
-            currently invokes the scorer's current default version.
+        scorer_version_id: Optional for legacy requests; required when the
+            contextual evaluator sends a structured record.
         scorer_label: Optional display/metadata label.
         threshold: Local threshold used by the evaluator for comparison.
         operator: Local comparison operator. Numeric operators use threshold as a number.
@@ -75,8 +75,8 @@ class LunaEvaluatorConfig(EvaluatorConfig):
         default=None,
         min_length=1,
         description=(
-            "Deprecated optional compatibility identifier. Orbit currently invokes "
-            "the scorer's current default version."
+            "Optional for legacy requests and required when contextual evaluation "
+            "sends a structured record."
         ),
     )
     scorer_label: str | None = Field(

evaluators/contrib/galileo/src/agent_control_evaluator_galileo/luna/evaluator.py

@@ -281,6 +281,8 @@ async def _evaluate(
             scorer_kwargs = self._scorer_kwargs()
             if step is not None:
                 scorer_kwargs["step"] = step
+                scorer_kwargs["selected_data"] = data
+                scorer_kwargs["selected_data_payload_field"] = self.config.payload_field
             if execution_context is not None:
                 scorer_kwargs["execution_context"] = execution_context
             response = await self._get_client().invoke(

evaluators/contrib/galileo/src/agent_control_evaluator_galileo/records/__init__.py

@@ -6,7 +6,6 @@
     UnsupportedStepTypeError,
     build_galileo_record,
     build_record,
-    record_from_scorer_invoke_record,
     record_from_step,
 )
 from .normalization import GalileoRecordNormalizer
@@ -18,6 +17,5 @@
     "UnsupportedStepTypeError",
     "build_galileo_record",
     "build_record",
-    "record_from_scorer_invoke_record",
     "record_from_step",
 ]