Field Normalization Strategies
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Field Normalization Strategies in Continuous Claude v2 are designed to handle inconsistencies in API field casing across different Model Context Protocol (MCP) servers. The system automatically converts inconsistent API field naming conventions into a standardized format to ensure reliable data processing and type safety within the runtime environment. Sources: CLAUDE.md:104, src/runtime/normalize_fields.py
The primary goal is to resolve discrepancies such as those found in Azure DevOps (ADO), where fields like system.parent may need to be transformed into System.Parent. This allows the AI agent and the execution harness to interact with diverse tools using a predictable schema. Sources: CLAUDE.md:73, tests/unit/test_normalize_fields.py:12-16
Core Architecture and Logic
The normalization logic is integrated into the tool execution pipeline. When a tool is called, the raw result is intercepted, processed through a normalization strategy assigned to that specific server, and then validated against Pydantic models. Sources: src/runtime/generate_wrappers.py:46-52
Normalization Workflow
The following diagram illustrates how data flows from an MCP server through the normalization layer before being returned to the user or agent.
The system identifies the server name and dispatches the request to the appropriate strategy via get_normalization_strategy. Sources: tests/unit/test_normalize_fields.py:108-114
Data Handling
Normalization is designed to be immutable, ensuring that the original data object remains unchanged while a new, normalized version is created. It handles nested dictionaries and lists through deep recursion. Sources: tests/unit/test_normalize_fields.py:64-88
| Feature | Description |
|---|---|
| Immutability | Returns a new object; does not modify the input in-place. |
| Recursion | Processes deep nested structures and lists. |
| Type Safety | Returns primitives (Strings, Ints, Booleans) unchanged. |
Sources: tests/unit/test_normalize_fields.py:53-88
Implementation Strategies
The project currently supports specific strategies mapped to server types.
ADO Pascal Case Strategy
This strategy is specifically tuned for Azure DevOps. It targets field prefixes and converts them to the expected PascalCase format. Sources: tests/unit/test_normalize_fields.py:12-40
| Pattern | Input Example | Normalized Example |
|---|---|---|
| System Fields | system.title | System.title |
| Microsoft Fields | microsoft.vsts.common.priority | Microsoft.vsts.common.priority |
| Custom Fields | custom.myfield | Custom.myfield |
| WEF Fields | wef_123 | WEF_123 |
Sources: tests/unit/test_normalize_fields.py:12-40
Integration with Code Generation
Normalization is automatically applied in the generated Python wrappers for MCP tools. The generate_tool_wrapper function injects a call to normalize_field_names into every tool function it creates. Sources: src/runtime/generate_wrappers.py:27-52
# snippet from generated wrapper logic
result = await call_mcp_tool("{tool_identifier}", params.model_dump(exclude_none=True))
unwrapped = getattr(result, "value", result)
normalized = normalize_field_names(unwrapped, "{server_name}")
return normalized
Sources: src/runtime/generate_wrappers.py:46-52
Component Overview
| Component | Function / Class | Description |
|---|---|---|
| Entry Point | normalize_field_names | Dispatches the object to a strategy based on the server name. |
| Strategy Resolver | get_normalization_strategy | Maps server names (e.g., 'ado', 'github') to strategies ('ado-pascal-case', 'none'). |
| ADO Strategy | normalize_ado_fields | Implements the specific logic for Azure DevOps field casing. |
| Config Manager | update_normalization_config | Allows runtime updates to server-to-strategy mappings. |
Sources: tests/unit/test_normalize_fields.py:5-10, tests/unit/test_normalize_fields.py:117-124
Artifact Normalization
Beyond API responses, the project applies normalization logic when indexing session artifacts like handoffs and plans. The parse_handoff function in the indexing script maps various status strings to a canonical set of outcomes for storage in the Context Graph database. Sources: scripts/artifact_index.py:84-106
The outcome mapping ensures that regardless of the terminology used in the markdown files, the search index remains consistent. Sources: scripts/artifact_index.py:100-112
Summary
Field Normalization Strategies provide a critical abstraction layer that protects the Continuous-Claude-v2 runtime from external API variability. By enforcing consistent casing and status mapping through automated strategies and generated wrappers, the system ensures that AI agents can interact with heterogeneous tools without encountering schema-related errors. Sources: CLAUDE.md:120, src/runtime/generate_wrappers.py:14-18