Input/Output Mapping

Map your function’s parameters and return values to Rhesis’s standardized request/response format. The SDK supports both automatic detection and manual configuration.

Auto-Mapping (Recommended)

Use standard field names for automatic detection:

auto_mapping.py
@endpoint()
def chat(input: str, conversation_id: str = None) -> dict:
    """Standard names auto-detect."""
    return {
        "output": process_message(input),
        "conversation_id": conversation_id,
    }

Standard fields:

Direction	Field	Description
Request	`input`	The user query or test prompt
Request	`conversation_id`	Conversation tracking identifier
Request	`context`	Additional context provided with the request
Request	`metadata`	Structured metadata passed to the endpoint
Request	`tool_calls`	Tool call data passed to the endpoint
Request	`files`	File attachments passed as `FileReference` objects
Request	`params`	Resolved experiment parameters available in request mappings
Response	`output`	The main response text
Response	`context`	Retrieval context (e.g., RAG sources)
Response	`metadata`	Structured response metadata (e.g., confidence scores)
Response	`tool_calls`	Tool/function calls made during response generation
Response	`conversation_id`	Conversation identifier for multi-turn tracking

session_id remains supported as a legacy alias for existing endpoints and mappings.

Manual Mapping

For custom parameter names or complex structures, provide explicit mappings:

manual_mapping.py
@endpoint(
    request_mapping={
        "user_query": "{{ input }}",
        "conv_id": "{{ conversation_id }}",
    },
    response_mapping={
        "output": "$.result.text",
        "conversation_id": "$.conv_id",
    },
)
def chat(user_query: str, conv_id: str = None) -> dict:
    """Custom names require manual mapping."""
    return {"result": {"text": "..."}, "conv_id": conv_id}

Request Mapping (Jinja2 Templates)

Request mapping transforms incoming Rhesis request fields to your function parameters using Jinja2 template syntax ({{ variable_name }}). Standard fields (see the table above) and any custom fields in the request are available as template variables.

Simple Mappings

simple_request.py
@endpoint(
    request_mapping={
        "user_message": "{{ input }}",
        "conv_id": "{{ conversation_id }}",
    }
)
def chat(user_message: str, conv_id: str = None) -> dict:
    return {"output": process(user_message)}

Complex Structures

For functions that accept complex types (like Pydantic models), mapping keys should match function parameter names:

complex_request.py
@endpoint(
    request_mapping={
        "request": {
            "messages": [{"role": "user", "content": "{{ input }}"}],
            "context": {"conversation_id": "{{ conversation_id }}"},
        },
    }
)
def agent(request: ChatAgentRequest) -> ChatAgentResponse:
    # The SDK automatically constructs ChatAgentRequest from the mapped dict
    return ChatAgentResponse(...)

See Advanced Mapping for how complex types like Pydantic models are automatically constructed from mapped dictionaries.

Experiment parameters

When a test run is associated with an experiment, resolved values are available under params. Prefer mapping those values into your function arguments instead of using the deprecated parameters= decorator option.

params_mapping.py
@endpoint(
    name="chat",
    request_mapping={
        "user_message": "{{ input }}",
        "model": "{{ params.model | default('gpt-4o') }}",
        "temperature": "{{ params.temperature | default(0.7) }}",
    },
    response_mapping={"output": "$.answer"},
)
def chat(user_message: str, *, model: str, temperature: float) -> dict:
    answer = llm.invoke(user_message, model=model, temperature=temperature)
    return {"answer": answer}

The legacy @endpoint(parameters=["model", "temperature"]) path still works for older applications, but it emits a deprecation warning. Use {{ params.* }} in request_mapping for new endpoints.

File attachments

Use the files variable when your endpoint needs test attachments. Map it directly into a function argument and handle the items as FileReference objects.

files_mapping.py
from rhesis.sdk.connector.types import FileReference

@endpoint(
    name="vision-check",
    request_mapping={
        "question": "{{ input }}",
        "files": "{{ files }}",
    },
    response_mapping={"output": "$.answer"},
)
def vision_check(question: str, files: list[FileReference]) -> dict:
    descriptions = [f.extracted_text or f.filename for f in files]
    return {"answer": answer_with_context(question, descriptions)}

See Connector Files for raw byte access and extraction details.

Response Mapping (JSONPath or Jinja2)

Response mapping extracts values from your function’s return value to Rhesis’s standardized format.

JSONPath Syntax

Use JSONPath expressions (starting with $) for direct field extraction:

jsonpath_response.py
@endpoint(
    response_mapping={
        "output": "$.choices[0].message.content",       # Nested extraction
        "conversation_id": "$.conv_id",                 # Top-level field
        "context": "$.sources",                         # Array field
        "metadata": "$.usage",                          # Structured metadata
        "tool_calls": "$.choices[0].message.tool_calls",# Tool call data
    }
)
def chat(input: str) -> dict:
    return {
        "choices": [{"message": {"content": "Hello!", "tool_calls": [...]}}],
        "conv_id": "abc123",
        "sources": ["doc1.pdf", "doc2.pdf"],
        "usage": {"prompt_tokens": 10, "completion_tokens": 20},
    }

Common JSONPath patterns:

Pattern	Description
`$.field`	Top-level field
`$.nested.field`	Nested field
`$.array[0]`	First array element
`$.array[-1]`	Last array element
`$.array[*].field`	Field from all array elements

Jinja2 Templates with JSONPath

Use Jinja2 templates with the jsonpath() function for conditional logic or complex extraction:

jinja2_response.py
@endpoint(
    response_mapping={
        # Try first path, fall back to second if empty
        "output": "{{ jsonpath('$.text_response') or jsonpath('$.result.content') }}",
        # Direct JSONPath still works
        "conversation_id": "$.conv_id",
    },
)
def chat(input: str) -> dict:
    """Extract output from multiple possible locations."""
    return {"text_response": "...", "conv_id": "abc123"}

Custom Request Fields

You can pass custom fields through the API that aren’t part of the standard schema:

custom_fields.py
@endpoint(
    request_mapping={
        "question": "{{ input }}",
        "policy_id": "{{ policy_number }}",  # Custom field from request
        "tier": "{{ customer_tier }}",        # Another custom field
    },
    response_mapping={"output": "$.answer"},
)
def insurance_query(question: str, policy_id: str, tier: str) -> dict:
    # Custom fields (policy_number, customer_tier) must be included in API request
    return {"answer": lookup_policy(question, policy_id, tier)}

Custom fields must be included in the API request body when invoking the endpoint.

Next steps

Map complex objects like Pydantic models and dataclasses.
Handle file attachments passed as FileReference objects.