langchain-content-normalizer

Normalize the messy content shapes produced by LangChain, MCP tools, Anthropic content blocks, and multimodal chat APIs.

The package has no runtime dependencies. It works by duck typing instead of importing LangChain or MCP classes.

What it solves

LLM agent stacks often receive content as one of many incompatible shapes:

Install

uv add langchain-content-normalizer

Text normalization

from lc_content_normalizer import extract_text_content, normalize_tool_output

content = [
    {"type": "text", "text": "Reading logs..."},
    {"type": "tool_use", "name": "tail_logs", "input": {"service": "api"}},
]

assert extract_text_content(content) == "Reading logs..."
assert "tail_logs" in extract_text_content(content, skip_tool_use=False)
assert extract_text_content(content, separator="\n") == "Reading logs..."

safe_output = normalize_tool_output(huge_tool_payload, max_chars=50_000, separator="\n")

Vision format routing

from lc_content_normalizer import build_human_message_content, detect_vision_format

vision_format = detect_vision_format("anthropic", "claude-3-5-sonnet")
content = build_human_message_content(
    "Explain this alert screenshot",
    images=[{"data_url": "data:image/png;base64,...", "mime_type": "image/png"}],
    vision_format=vision_format,
)

detect_vision_format() returns:

Examples

• examples/normalize_mcp_output.py shows how MCP-style tool results are flattened.
• examples/build_vision_content.py shows provider-aware image block generation.

Roadmap

• Add provider-specific adapters as content formats evolve.
• Keep runtime dependencies at zero.

Strict mode

By default, unknown non-empty content is preserved with str(...) so tool output is not silently lost. Use strict mode when unknown shapes should fail fast:

from lc_content_normalizer import UnknownContentBlockError, extract_text_content

try:
    extract_text_content([{"type": "custom", "payload": "..."}], strict=True)
except UnknownContentBlockError:
    ...

Development

uv sync --dev
uv run ruff check .
uv run pytest
uv run python scripts/smoke.py
uv build

License

MIT