langchain-content-normalizer 0.1.0__py3-none-any.whl

langchain_content_normalizer-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: langchain-content-normalizer
+Version: 0.1.0
+Summary: Normalize LangChain, MCP, and multimodal content blocks into provider-ready text and image payloads.
+Project-URL: Homepage, https://github.com/benjaminjornet/langchain-content-normalizer
+Project-URL: Issues, https://github.com/benjaminjornet/langchain-content-normalizer/issues
+Author-email: Benjamin Jornet <benjamin.jornet@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Benjamin Jornet
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: content-normalization,langchain,llm,mcp,multimodal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# langchain-content-normalizer
+
+[![CI](https://github.com/BenjaminJornet/langchain-content-normalizer/actions/workflows/ci.yml/badge.svg)](https://github.com/BenjaminJornet/langchain-content-normalizer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+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:
+
+| Source | Example shape | Output |
+| --- | --- | --- |
+| Classic chat | `"plain text"` | `"plain text"` |
+| Anthropic blocks | `[{"type": "text", "text": "hi"}]` | `"hi"` |
+| Tool calls | `[{"type": "tool_use", ...}]` | skipped by default |
+| MCP tool results | `[{"type": "tool_result", "content": [...]}]` | flattened text |
+| MCP objects | objects exposing `.text` | extracted text |
+| Message wrappers | objects exposing `.content` | recursively normalized |
+
+## Install
+
+```bash
+uv add langchain-content-normalizer
+```
+
+## Text normalization
+
+```python
+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)
+
+safe_output = normalize_tool_output(huge_tool_payload, max_chars=50_000)
+```
+
+## Vision format routing
+
+```python
+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:
+
+| Provider/model | Format |
+| --- | --- |
+| `anthropic` | native Anthropic `image` block with `source.base64` |
+| `ollama` + `llava`/`vision` model name | OpenAI-compatible `image_url` block |
+| `ollama` text-only model | `none`, images are dropped |
+| OpenAI-compatible providers | OpenAI-compatible `image_url` block |
+
+## 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 strict mode for unknown content blocks.
+- Add more MCP fixture coverage.
+- Add provider-specific adapters as content formats evolve.
+- Keep runtime dependencies at zero.
+
+## Development
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run pytest
+uv run python scripts/smoke.py
+```
+
+## License
+
+MIT

langchain_content_normalizer-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+lc_content_normalizer/__init__.py,sha256=kzmKj1eLlp5crQclwE28v3pE091nyjX5mLja_FIfmiE,516
+lc_content_normalizer/text.py,sha256=-TQjxZwXUJoaZpXlxjzt-qo78Y5m8XJhjayW48yAAwI,2729
+lc_content_normalizer/vision.py,sha256=Q2VPgSafQtXfNpBlc41YBIETQvGT46a26zZp2zl9A0o,1870
+langchain_content_normalizer-0.1.0.dist-info/METADATA,sha256=7SI4OsoNCJoZYizynLImejdN800F1vCOd9v8WK-LWcw,5096
+langchain_content_normalizer-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+langchain_content_normalizer-0.1.0.dist-info/licenses/LICENSE,sha256=WdZfrCBxqj0eY04I5UNmeuqGPeyWa4YGULcHq6cWXS8,1072
+langchain_content_normalizer-0.1.0.dist-info/RECORD,,

langchain_content_normalizer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_content_normalizer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Jornet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lc_content_normalizer/__init__.py

@@ -0,0 +1,20 @@
+from .text import extract_text_content, normalize_tool_output
+from .vision import (
+    VISION_FORMAT_ANTHROPIC_NATIVE,
+    VISION_FORMAT_NONE,
+    VISION_FORMAT_OPENAI,
+    build_human_message_content,
+    detect_vision_format,
+    image_block_for_format,
+)
+
+__all__ = [
+    "VISION_FORMAT_ANTHROPIC_NATIVE",
+    "VISION_FORMAT_NONE",
+    "VISION_FORMAT_OPENAI",
+    "build_human_message_content",
+    "detect_vision_format",
+    "extract_text_content",
+    "image_block_for_format",
+    "normalize_tool_output",
+]

lc_content_normalizer/text.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_text_content(content: Any, *, skip_tool_use: bool = True) -> str:
+    """Normalize LangChain, Anthropic, and MCP content shapes to plain text.
+
+    Supported inputs include strings, Anthropic-style content block lists,
+    MCP TextContent-like objects exposing ``.text``, and message-like objects
+    exposing ``.content``. Unknown non-empty block lists fall back to ``str`` so
+    tool outputs are not silently lost.
+    """
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        saw_known_block = False
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+                saw_known_block = True
+                continue
+            if isinstance(block, dict):
+                block_type = block.get("type")
+                if block_type == "text" and isinstance(block.get("text"), str):
+                    parts.append(block["text"])
+                    saw_known_block = True
+                elif block_type == "tool_result":
+                    parts.append(
+                        extract_text_content(block.get("content", ""), skip_tool_use=skip_tool_use)
+                    )
+                    saw_known_block = True
+                elif block_type == "tool_use":
+                    saw_known_block = True
+                    if not skip_tool_use:
+                        parts.append(str(block.get("input", "")))
+                elif block_type in {"image", "image_url"}:
+                    saw_known_block = True
+                continue
+
+            text_attr = getattr(block, "text", None)
+            if isinstance(text_attr, str):
+                parts.append(text_attr)
+                saw_known_block = True
+                continue
+
+            parts.append(str(block))
+
+        result = "".join(parts)
+        if not result and content and not saw_known_block:
+            return str(content)
+        return result
+
+    inner = getattr(content, "content", None)
+    if inner is not None and inner is not content:
+        return extract_text_content(inner, skip_tool_use=skip_tool_use)
+
+    text_attr = getattr(content, "text", None)
+    if isinstance(text_attr, str):
+        return text_attr
+
+    return str(content)
+
+
+def normalize_tool_output(raw: Any, *, max_chars: int = 50_000) -> str:
+    """Extract a readable tool output string and truncate oversized payloads."""
+    text = extract_text_content(raw)
+    if len(text) <= max_chars:
+        return text
+    omitted = len(text) - max_chars
+    return text[:max_chars] + f"\n\n[...truncated {omitted} chars]"

lc_content_normalizer/vision.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+VISION_FORMAT_OPENAI = "openai"
+VISION_FORMAT_ANTHROPIC_NATIVE = "anthropic_native"
+VISION_FORMAT_NONE = "none"
+
+
+def detect_vision_format(provider: str, model: str) -> str:
+    """Pick the multimodal block format expected by a provider/model pair."""
+    provider_name = (provider or "").lower()
+    model_name = (model or "").lower()
+
+    if provider_name == "anthropic":
+        return VISION_FORMAT_ANTHROPIC_NATIVE
+    if provider_name == "ollama":
+        if "llava" in model_name or "vision" in model_name:
+            return VISION_FORMAT_OPENAI
+        return VISION_FORMAT_NONE
+    return VISION_FORMAT_OPENAI
+
+
+def image_block_for_format(image: dict[str, str], vision_format: str) -> dict[str, Any]:
+    """Render one image into the multimodal block expected by the target API."""
+    if vision_format == VISION_FORMAT_ANTHROPIC_NATIVE:
+        data_url = image.get("data_url", "")
+        header, _, b64_data = data_url.partition(",")
+        media_type = image.get("mime_type") or header.removeprefix("data:").split(";", 1)[0]
+        return {
+            "type": "image",
+            "source": {"type": "base64", "media_type": media_type, "data": b64_data},
+        }
+    return {"type": "image_url", "image_url": {"url": image["data_url"]}}
+
+
+def build_human_message_content(
+    text: str,
+    images: list[dict[str, str]] | None = None,
+    vision_format: str = VISION_FORMAT_OPENAI,
+) -> str | list[dict[str, Any]]:
+    """Build text-only or multimodal human message content for LangChain."""
+    if not images or vision_format == VISION_FORMAT_NONE:
+        return text
+
+    content: list[dict[str, Any]] = []
+    if text:
+        content.append({"type": "text", "text": text})
+    for image in images:
+        content.append(image_block_for_format(image, vision_format))
+    return content