llm-io-normalizer 0.1.0__tar.gz

llm_io_normalizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llm-io-normalizer contributors
+
+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.

llm_io_normalizer-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: llm-io-normalizer
+Version: 0.1.0
+Summary: A lightweight Model I/O normalization layer for OpenAI-compatible LLM calls.
+Author: llm-io-normalizer contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wanghesong2019/llm-io-normalizer
+Project-URL: Repository, https://github.com/wanghesong2019/llm-io-normalizer
+Project-URL: Issues, https://github.com/wanghesong2019/llm-io-normalizer/issues
+Keywords: llm,model-io,openai-compatible,reasoning,streaming,normalization,judge-model,tested-model,structured-output
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# llm-io-normalizer
+
+`llm-io-normalizer` is a lightweight **Model I/O normalization layer** for OpenAI-compatible LLM calls.
+It is built for applications that call both **tested models** and **judge models** and need a stable result contract instead of provider-specific response parsing.
+
+It normalizes common LLM response differences such as:
+
+- `message.content` vs `message.reasoning`
+- `delta.content` vs `delta.reasoning` / `delta.reasoning_content`
+- `<think>...</think>` reasoning mixed into normal content
+- stream vs non-stream completion behavior
+- successful HTTP responses that contain reasoning but no final answer
+- final JSON extraction from model output
+
+The public contract is intentionally small and stable:
+
+```python
+result.answer_text
+result.reasoning_text
+result.ok
+result.error_type
+result.error_message
+```
+
+Business code should depend on these normalized fields instead of reading raw provider fields directly.
+
+## Install
+
+After publishing to PyPI:
+
+```bash
+pip install llm-io-normalizer
+```
+
+From a local checkout:
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from llm_io_normalizer import LLMGateway, LLMRequest, LLMRole
+
+
+async def main() -> None:
+    gateway = LLMGateway()
+
+    result = await gateway.generate(
+        LLMRequest(
+            role=LLMRole.JUDGE_MODEL,
+            model_name="your-model-name",
+            base_url="https://example.com/v1",
+            api_key="YOUR_API_KEY",
+            messages=[
+                {"role": "system", "content": "You are a strict JSON judge."},
+                {"role": "user", "content": "Return {\"result\": 2}."},
+            ],
+            # Judge models should usually prefer stable non-stream output.
+            stream=False,
+            enable_thinking=False,
+            temperature=0,
+            max_tokens=1024,
+        )
+    )
+
+    result.require_ok()
+    print(result.answer_text)
+
+
+asyncio.run(main())
+```
+
+## Core concepts
+
+### Tested model calls
+
+`LLMRole.TESTED_MODEL` is for the model being evaluated or observed.
+
+Default behavior:
+
+- streams by default unless `stream=False` is provided
+- can collect native reasoning fields from compatible providers
+- can split `<think>...</think>` blocks out of the answer
+- returns clean `answer_text` and separate `reasoning_text`
+- can retry without thinking when the provider returns no final answer
+
+### Judge model calls
+
+`LLMRole.JUDGE_MODEL` is for scoring, evaluation, moderation, ranking, or structured judgment tasks.
+
+Default behavior:
+
+- uses non-stream mode by default unless `stream=True` is provided
+- is designed for stable final output, especially JSON scoring results
+- usually pairs well with `enable_thinking=False` and `temperature=0`
+- marks the call as `ok=False` with `error_type="EMPTY_ANSWER"` when the provider returns reasoning but no final answer
+
+## JSON output helper
+
+```python
+from llm_io_normalizer.normalizers import extract_json_object
+
+obj = extract_json_object('```json\n{"result": 2}\n```')
+assert obj == {"result": 2}
+```
+
+## Examples
+
+The `examples/` directory contains runnable examples for:
+
+- tested-model calls
+- judge-model calls
+- a tested-model → judge-model evaluation pipeline
+
+Use environment variables for provider credentials and endpoints when running examples:
+
+```bash
+export LLM_BASE_URL="https://your-provider.example/v1"
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="your-model-name"
+python examples/judge_model.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+## Release
+
+Recommended PyPI release mode is **Trusted Publishing** from GitHub Actions.
+Configure the PyPI project to trust this repository workflow, then publish a GitHub release tag such as `v0.1.0`.
+
+## Scope
+
+This package is intentionally **not** a full API gateway.
+It does not implement authentication, rate limiting, billing, routing dashboards, or multi-tenant governance.
+Those can be handled by an outer gateway such as Kong, APISIX, Envoy, Portkey, or other infrastructure.
+
+`llm-io-normalizer` focuses on the reusable Python SDK layer:
+
+- Model I/O normalization
+- reasoning / answer separation
+- stream / non-stream fallback
+- tested-model and judge-model call policies
+- unified result/error contract
+- simple JSON object extraction from model output

llm_io_normalizer-0.1.0/README.md

@@ -0,0 +1,161 @@
+# llm-io-normalizer
+
+`llm-io-normalizer` is a lightweight **Model I/O normalization layer** for OpenAI-compatible LLM calls.
+It is built for applications that call both **tested models** and **judge models** and need a stable result contract instead of provider-specific response parsing.
+
+It normalizes common LLM response differences such as:
+
+- `message.content` vs `message.reasoning`
+- `delta.content` vs `delta.reasoning` / `delta.reasoning_content`
+- `<think>...</think>` reasoning mixed into normal content
+- stream vs non-stream completion behavior
+- successful HTTP responses that contain reasoning but no final answer
+- final JSON extraction from model output
+
+The public contract is intentionally small and stable:
+
+```python
+result.answer_text
+result.reasoning_text
+result.ok
+result.error_type
+result.error_message
+```
+
+Business code should depend on these normalized fields instead of reading raw provider fields directly.
+
+## Install
+
+After publishing to PyPI:
+
+```bash
+pip install llm-io-normalizer
+```
+
+From a local checkout:
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from llm_io_normalizer import LLMGateway, LLMRequest, LLMRole
+
+
+async def main() -> None:
+    gateway = LLMGateway()
+
+    result = await gateway.generate(
+        LLMRequest(
+            role=LLMRole.JUDGE_MODEL,
+            model_name="your-model-name",
+            base_url="https://example.com/v1",
+            api_key="YOUR_API_KEY",
+            messages=[
+                {"role": "system", "content": "You are a strict JSON judge."},
+                {"role": "user", "content": "Return {\"result\": 2}."},
+            ],
+            # Judge models should usually prefer stable non-stream output.
+            stream=False,
+            enable_thinking=False,
+            temperature=0,
+            max_tokens=1024,
+        )
+    )
+
+    result.require_ok()
+    print(result.answer_text)
+
+
+asyncio.run(main())
+```
+
+## Core concepts
+
+### Tested model calls
+
+`LLMRole.TESTED_MODEL` is for the model being evaluated or observed.
+
+Default behavior:
+
+- streams by default unless `stream=False` is provided
+- can collect native reasoning fields from compatible providers
+- can split `<think>...</think>` blocks out of the answer
+- returns clean `answer_text` and separate `reasoning_text`
+- can retry without thinking when the provider returns no final answer
+
+### Judge model calls
+
+`LLMRole.JUDGE_MODEL` is for scoring, evaluation, moderation, ranking, or structured judgment tasks.
+
+Default behavior:
+
+- uses non-stream mode by default unless `stream=True` is provided
+- is designed for stable final output, especially JSON scoring results
+- usually pairs well with `enable_thinking=False` and `temperature=0`
+- marks the call as `ok=False` with `error_type="EMPTY_ANSWER"` when the provider returns reasoning but no final answer
+
+## JSON output helper
+
+```python
+from llm_io_normalizer.normalizers import extract_json_object
+
+obj = extract_json_object('```json\n{"result": 2}\n```')
+assert obj == {"result": 2}
+```
+
+## Examples
+
+The `examples/` directory contains runnable examples for:
+
+- tested-model calls
+- judge-model calls
+- a tested-model → judge-model evaluation pipeline
+
+Use environment variables for provider credentials and endpoints when running examples:
+
+```bash
+export LLM_BASE_URL="https://your-provider.example/v1"
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="your-model-name"
+python examples/judge_model.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+## Release
+
+Recommended PyPI release mode is **Trusted Publishing** from GitHub Actions.
+Configure the PyPI project to trust this repository workflow, then publish a GitHub release tag such as `v0.1.0`.
+
+## Scope
+
+This package is intentionally **not** a full API gateway.
+It does not implement authentication, rate limiting, billing, routing dashboards, or multi-tenant governance.
+Those can be handled by an outer gateway such as Kong, APISIX, Envoy, Portkey, or other infrastructure.
+
+`llm-io-normalizer` focuses on the reusable Python SDK layer:
+
+- Model I/O normalization
+- reasoning / answer separation
+- stream / non-stream fallback
+- tested-model and judge-model call policies
+- unified result/error contract
+- simple JSON object extraction from model output

llm_io_normalizer-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llm-io-normalizer"
+version = "0.1.0"
+description = "A lightweight Model I/O normalization layer for OpenAI-compatible LLM calls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  {name = "llm-io-normalizer contributors"}
+]
+keywords = [
+  "llm",
+  "model-io",
+  "openai-compatible",
+  "reasoning",
+  "streaming",
+  "normalization",
+  "judge-model",
+  "tested-model",
+  "structured-output"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+  "build>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/wanghesong2019/llm-io-normalizer"
+Repository = "https://github.com/wanghesong2019/llm-io-normalizer"
+Issues = "https://github.com/wanghesong2019/llm-io-normalizer/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+llm_io_normalizer = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

llm_io_normalizer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llm_io_normalizer-0.1.0/src/llm_io_normalizer/__init__.py

@@ -0,0 +1,4 @@
+from llm_io_normalizer.gateway import LLMGateway
+from llm_io_normalizer.schemas import LLMMode, LLMRequest, LLMResult, LLMRole
+
+__all__ = ["LLMGateway", "LLMMode", "LLMRequest", "LLMResult", "LLMRole"]

llm_io_normalizer-0.1.0/src/llm_io_normalizer/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .openai_compatible import OpenAICompatibleGateway
+
+__all__ = ["OpenAICompatibleGateway"]

llm_io_normalizer-0.1.0/src/llm_io_normalizer/adapters/openai_compatible.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from llm_io_normalizer.normalizers import normalize_reasoning_answer
+from llm_io_normalizer.schemas import LLMMode, LLMRequest, LLMResult, LLMRole
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAICompatibleGateway:
+    """OpenAI-compatible adapter with Model IO normalization.
+
+    This adapter intentionally keeps provider-specific return fields out of
+    business code. It collects content/reasoning from common stream and
+    non-stream locations, then normalizes them into answer_text/reasoning_text.
+    """
+
+    def __init__(self, *, default_timeout: float | None = 120) -> None:
+        self.default_timeout = default_timeout
+
+    async def generate(self, request: LLMRequest) -> LLMResult:
+        role = request.normalized_role()
+        stream = self._select_stream_default(request, role)
+
+        if stream:
+            result = await self._generate_stream(request)
+            if result.ok:
+                return result
+
+            if request.fallback_to_non_stream and result.error_type == "EMPTY_ANSWER":
+                logger.warning(
+                    "[LLMGatewayFallback] model=%s role=%s action=retry_non_stream reason=%s",
+                    request.model_name,
+                    role.value,
+                    result.error_message,
+                )
+                return await self._generate_non_stream(request.with_updates(stream=False))
+            return result
+
+        result = await self._generate_non_stream(request)
+        if result.ok:
+            return result
+
+        # For tested models, if thinking consumed the final answer, retry once without thinking.
+        if (
+            role == LLMRole.TESTED_MODEL
+            and request.retry_without_thinking_when_empty
+            and request.enable_thinking is True
+            and result.error_type == "EMPTY_ANSWER"
+        ):
+            logger.warning(
+                "[LLMGatewayFallback] model=%s role=%s action=retry_without_thinking",
+                request.model_name,
+                role.value,
+            )
+            return await self.generate(request.with_updates(enable_thinking=False))
+
+        return result
+
+    def _select_stream_default(self, request: LLMRequest, role: LLMRole) -> bool:
+        if request.stream is not None:
+            return bool(request.stream)
+        # Judge calls should prefer non-stream because final JSON should be stable.
+        if role == LLMRole.JUDGE_MODEL:
+            return False
+        return True
+
+    def _client(self, request: LLMRequest):
+        from openai import OpenAI
+
+        kwargs: dict[str, Any] = {}
+        if request.api_key:
+            kwargs["api_key"] = request.api_key
+        if request.base_url:
+            kwargs["base_url"] = request.base_url
+        timeout = request.timeout if request.timeout is not None else self.default_timeout
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return OpenAI(**kwargs)
+
+    def _extra_body(self, request: LLMRequest) -> dict[str, Any] | None:
+        body = dict(request.extra_body or {})
+        if request.enable_thinking is not None:
+            body.setdefault("enable_thinking", request.enable_thinking)
+        return body or None
+
+    def _common_kwargs(self, request: LLMRequest) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {
+            "model": request.model_name,
+            "messages": request.messages,
+        }
+        if request.temperature is not None:
+            kwargs["temperature"] = request.temperature
+        if request.top_p is not None:
+            kwargs["top_p"] = request.top_p
+        if request.max_tokens is not None:
+            kwargs["max_tokens"] = request.max_tokens
+        extra_body = self._extra_body(request)
+        if extra_body is not None:
+            kwargs["extra_body"] = extra_body
+        return kwargs
+
+    async def _generate_non_stream(self, request: LLMRequest) -> LLMResult:
+        client = self._client(request)
+        kwargs = self._common_kwargs(request)
+        kwargs["stream"] = False
+
+        logger.info(
+            "[LLMGatewayRequest] mode=non_stream role=%s model=%s messages=%s",
+            request.normalized_role().value,
+            request.model_name,
+            len(request.messages),
+        )
+
+        try:
+            response = await asyncio.to_thread(lambda: client.chat.completions.create(**kwargs))
+        except Exception as exc:
+            logger.exception("[LLMGatewayError] mode=non_stream model=%s", request.model_name)
+            return LLMResult(
+                ok=False,
+                model_name=request.model_name,
+                mode=LLMMode.NON_STREAM,
+                error_type="PROVIDER_ERROR",
+                error_message=str(exc),
+            )
+
+        if not response.choices:
+            return LLMResult(
+                ok=False,
+                model_name=request.model_name,
+                mode=LLMMode.NON_STREAM,
+                error_type="EMPTY_CHOICES",
+                error_message="Provider returned no choices.",
+            )
+
+        choice = response.choices[0]
+        msg = choice.message
+        finish_reason = getattr(choice, "finish_reason", None)
+
+        content_text = getattr(msg, "content", None) or ""
+        native_reasoning = self._extract_message_reasoning(msg)
+        usage = self._safe_model_dump(getattr(response, "usage", None))
+
+        return self._finalize_result(
+            request=request,
+            mode=LLMMode.NON_STREAM,
+            content_text=content_text,
+            native_reasoning_text=native_reasoning,
+            finish_reason=finish_reason,
+            usage=usage,
+            raw_chunks_sample=[],
+        )
+
+    async def _generate_stream(self, request: LLMRequest) -> LLMResult:
+        client = self._client(request)
+        kwargs = self._common_kwargs(request)
+        kwargs["stream"] = True
+
+        logger.info(
+            "[LLMGatewayRequest] mode=stream role=%s model=%s messages=%s",
+            request.normalized_role().value,
+            request.model_name,
+            len(request.messages),
+        )
+
+        content_text = ""
+        native_reasoning = ""
+        finish_reason: str | None = None
+        raw_chunks_sample: list[dict[str, Any]] = []
+        chunk_count = 0
+
+        try:
+            stream = await asyncio.to_thread(lambda: client.chat.completions.create(**kwargs))
+            for chunk in stream:
+                chunk_count += 1
+                if len(raw_chunks_sample) < 3:
+                    raw_chunks_sample.append(self._safe_model_dump(chunk))
+
+                if not getattr(chunk, "choices", None):
+                    continue
+                choice = chunk.choices[0]
+                if getattr(choice, "finish_reason", None):
+                    finish_reason = choice.finish_reason
+                delta = getattr(choice, "delta", None)
+                if delta is None:
+                    continue
+
+                content_text += self._extract_delta_content(delta)
+                native_reasoning += self._extract_delta_reasoning(delta)
+        except Exception as exc:
+            logger.exception("[LLMGatewayError] mode=stream model=%s", request.model_name)
+            return LLMResult(
+                ok=False,
+                model_name=request.model_name,
+                mode=LLMMode.STREAM,
+                error_type="PROVIDER_ERROR",
+                error_message=str(exc),
+                raw_chunks_sample=raw_chunks_sample,
+            )
+
+        result = self._finalize_result(
+            request=request,
+            mode=LLMMode.STREAM,
+            content_text=content_text,
+            native_reasoning_text=native_reasoning,
+            finish_reason=finish_reason,
+            usage={},
+            raw_chunks_sample=raw_chunks_sample,
+        )
+        result.metadata.update({"chunk_count": chunk_count})
+        return result
+
+    def _finalize_result(
+        self,
+        *,
+        request: LLMRequest,
+        mode: LLMMode,
+        content_text: str,
+        native_reasoning_text: str,
+        finish_reason: str | None,
+        usage: dict[str, Any],
+        raw_chunks_sample: list[dict[str, Any]],
+    ) -> LLMResult:
+        normalized = normalize_reasoning_answer(
+            content_text=content_text,
+            native_reasoning_text=native_reasoning_text,
+            role=request.normalized_role().value,
+        )
+
+        answer = normalized.answer_text
+        reasoning = normalized.reasoning_text
+
+        ok = bool(answer.strip())
+        error_type = None if ok else "EMPTY_ANSWER"
+        error_message = None
+        if not ok:
+            if native_reasoning_text.strip():
+                error_message = "Provider returned reasoning but no final answer content."
+            else:
+                error_message = "Provider returned no final answer content."
+
+        logger.info(
+            "[LLMGatewayResult] mode=%s role=%s model=%s ok=%s answer_len=%s reasoning_len=%s parse=%s",
+            mode.value,
+            request.normalized_role().value,
+            request.model_name,
+            ok,
+            len(answer or ""),
+            len(reasoning or ""),
+            normalized.parse_method,
+        )
+
+        return LLMResult(
+            ok=ok,
+            model_name=request.model_name,
+            mode=mode,
+            answer_text=answer,
+            reasoning_text=reasoning,
+            raw_text=normalized.raw_text,
+            content_text=content_text,
+            native_reasoning_text=native_reasoning_text,
+            finish_reason=finish_reason,
+            usage=usage,
+            parse_method=normalized.parse_method,
+            confidence=normalized.confidence,
+            error_type=error_type,
+            error_message=error_message,
+            raw_chunks_sample=raw_chunks_sample,
+            metadata={"role": request.normalized_role().value},
+        )
+
+    def _extract_message_reasoning(self, msg: Any) -> str:
+        parts: list[str] = []
+        for field in ("reasoning", "reasoning_content", "thoughts", "reason"):
+            value = getattr(msg, field, None)
+            if value:
+                parts.append(str(value))
+        if isinstance(msg, dict):
+            for field in ("reasoning", "reasoning_content", "thoughts", "reason"):
+                if msg.get(field):
+                    parts.append(str(msg[field]))
+        return "".join(parts)
+
+    def _extract_delta_content(self, delta: Any) -> str:
+        value = getattr(delta, "content", None)
+        if value:
+            return str(value)
+        if isinstance(delta, dict) and delta.get("content"):
+            return str(delta["content"])
+        return ""
+
+    def _extract_delta_reasoning(self, delta: Any) -> str:
+        parts: list[str] = []
+        for field in ("reasoning", "reasoning_content", "thoughts", "reason"):
+            value = getattr(delta, field, None)
+            if value:
+                parts.append(str(value))
+        if isinstance(delta, dict):
+            for field in ("reasoning", "reasoning_content", "thoughts", "reason"):
+                if delta.get(field):
+                    parts.append(str(delta[field]))
+        return "".join(parts)
+
+    def _safe_model_dump(self, obj: Any) -> dict[str, Any]:
+        if obj is None:
+            return {}
+        if isinstance(obj, dict):
+            return obj
+        if hasattr(obj, "model_dump"):
+            try:
+                return obj.model_dump()
+            except Exception:
+                pass
+        if hasattr(obj, "dict"):
+            try:
+                return obj.dict()
+            except Exception:
+                pass
+        try:
+            return json.loads(json.dumps(obj, default=str))
+        except Exception:
+            return {"repr": repr(obj)}

llm_io_normalizer-0.1.0/src/llm_io_normalizer/errors.py

@@ -0,0 +1,10 @@
+class LLMGatewayError(RuntimeError):
+    """Base gateway error."""
+
+
+class LLMEmptyOutputError(LLMGatewayError):
+    """The provider returned HTTP success but no usable final answer."""
+
+
+class LLMProviderError(LLMGatewayError):
+    """The provider call failed."""

llm_io_normalizer-0.1.0/src/llm_io_normalizer/gateway.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from llm_io_normalizer.adapters import OpenAICompatibleGateway
+from llm_io_normalizer.schemas import LLMRequest, LLMResult
+
+
+class LLMGateway:
+    """Facade for Model IO normalization.
+
+    The first release delegates to an OpenAI-compatible adapter. Additional
+    adapters can be added without changing business code.
+    """
+
+    def __init__(self, adapter: OpenAICompatibleGateway | None = None) -> None:
+        self.adapter = adapter or OpenAICompatibleGateway()
+
+    async def generate(self, request: LLMRequest) -> LLMResult:
+        return await self.adapter.generate(request)

llm_io_normalizer-0.1.0/src/llm_io_normalizer/normalizers/__init__.py

@@ -0,0 +1,10 @@
+from .json_output import extract_json_object
+from .reasoning import NormalizedText, normalize_reasoning_answer, split_think_tag, strip_think_tags
+
+__all__ = [
+    "NormalizedText",
+    "extract_json_object",
+    "normalize_reasoning_answer",
+    "split_think_tag",
+    "strip_think_tags",
+]

llm_io_normalizer-0.1.0/src/llm_io_normalizer/normalizers/json_output.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def extract_json_object(text: str) -> dict[str, Any] | None:
+    """Extract and parse the first JSON object from model output."""
+    if not text:
+        return None
+
+    cleaned = text.strip()
+    try:
+        parsed = json.loads(cleaned)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+
+    # Remove markdown fences if present.
+    cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned, flags=re.IGNORECASE).strip()
+    cleaned = re.sub(r"\s*```$", "", cleaned).strip()
+    try:
+        parsed = json.loads(cleaned)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+
+    # Last resort: find the first {...} block.
+    match = re.search(r"\{.*\}", cleaned, flags=re.DOTALL)
+    if not match:
+        return None
+    try:
+        parsed = json.loads(match.group(0))
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        return None
+    return None

llm_io_normalizer-0.1.0/src/llm_io_normalizer/normalizers/reasoning.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_THINK_RE = re.compile(r"<think>\s*(.*?)\s*</think>", re.IGNORECASE | re.DOTALL)
+
+
+@dataclass(frozen=True)
+class NormalizedText:
+    reasoning_text: str
+    answer_text: str
+    raw_text: str
+    parse_method: str
+    confidence: float
+
+
+def strip_think_tags(text: str) -> str:
+    if not text:
+        return ""
+    return _THINK_RE.sub("", text).replace("<think>", "").replace("</think>", "").strip()
+
+
+def split_think_tag(raw_text: str) -> NormalizedText | None:
+    """Split '<think>...</think>final answer' style output."""
+    raw_text = raw_text or ""
+    match = _THINK_RE.search(raw_text)
+    if not match:
+        return None
+
+    reasoning = match.group(1).strip()
+    answer = (raw_text[: match.start()] + raw_text[match.end() :]).strip()
+    answer = answer.replace("<think>", "").replace("</think>", "").strip()
+    return NormalizedText(
+        reasoning_text=reasoning,
+        answer_text=answer,
+        raw_text=raw_text,
+        parse_method="think_tag",
+        confidence=0.95,
+    )
+
+
+def normalize_reasoning_answer(
+    *,
+    content_text: str,
+    native_reasoning_text: str = "",
+    role: str = "tested_model",
+) -> NormalizedText:
+    """Normalize provider-specific content/reasoning channels.
+
+    Rules:
+    - If a native reasoning channel exists, final answer is content_text.
+    - Else, if content has <think>...</think>, split it.
+    - Else, entire content is the answer.
+    """
+    content_text = content_text or ""
+    native_reasoning_text = native_reasoning_text or ""
+    raw_text = content_text
+
+    if native_reasoning_text.strip():
+        # Do not merge reasoning into answer; keep final answer clean.
+        return NormalizedText(
+            reasoning_text=native_reasoning_text.strip(),
+            answer_text=strip_think_tags(content_text),
+            raw_text=raw_text,
+            parse_method="native_reasoning",
+            confidence=0.95,
+        )
+
+    split = split_think_tag(content_text)
+    if split is not None:
+        return split
+
+    return NormalizedText(
+        reasoning_text="",
+        answer_text=content_text.strip(),
+        raw_text=raw_text,
+        parse_method="content_only",
+        confidence=0.70,
+    )

llm_io_normalizer-0.1.0/src/llm_io_normalizer/schemas.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import Any, Literal
+
+
+class LLMRole(str, Enum):
+    """Role-specific call policy."""
+
+    TESTED_MODEL = "tested_model"
+    JUDGE_MODEL = "judge_model"
+
+
+class LLMMode(str, Enum):
+    STREAM = "stream"
+    NON_STREAM = "non_stream"
+
+
+@dataclass(frozen=True)
+class LLMRequest:
+    """Portable request contract for an LLM call.
+
+    `role` is deliberately part of the request because tested-model calls and
+    judge-model calls should use different defaults.
+    """
+
+    model_name: str
+    messages: list[dict[str, Any]]
+    role: LLMRole | str = LLMRole.TESTED_MODEL
+
+    api_key: str | None = None
+    base_url: str | None = None
+
+    stream: bool | None = None
+    enable_thinking: bool | None = None
+    temperature: float | None = None
+    top_p: float | None = None
+    max_tokens: int | None = None
+
+    response_format: Literal["text", "json"] = "text"
+    timeout: float | None = None
+    extra_body: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Fallback behavior
+    fallback_to_non_stream: bool = True
+    retry_without_thinking_when_empty: bool = True
+
+    def normalized_role(self) -> LLMRole:
+        if isinstance(self.role, LLMRole):
+            return self.role
+        return LLMRole(self.role)
+
+    def with_updates(self, **updates: Any) -> LLMRequest:
+        return replace(self, **updates)
+
+
+@dataclass(frozen=True)
+class LLMResult:
+    """Portable result contract returned by gateway.generate()."""
+
+    ok: bool
+    model_name: str
+    mode: LLMMode | str
+
+    answer_text: str = ""
+    reasoning_text: str = ""
+    raw_text: str = ""
+
+    # Low-level raw channels before final normalization
+    content_text: str = ""
+    native_reasoning_text: str = ""
+
+    finish_reason: str | None = None
+    usage: dict[str, Any] = field(default_factory=dict)
+
+    parse_method: str | None = None
+    confidence: float | None = None
+
+    error_type: str | None = None
+    error_message: str | None = None
+
+    raw_chunks_sample: list[dict[str, Any]] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def require_ok(self) -> LLMResult:
+        if not self.ok:
+            raise RuntimeError(f"LLM call failed: {self.error_type}: {self.error_message}")
+        return self

llm_io_normalizer-0.1.0/src/llm_io_normalizer.egg-info/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: llm-io-normalizer
+Version: 0.1.0
+Summary: A lightweight Model I/O normalization layer for OpenAI-compatible LLM calls.
+Author: llm-io-normalizer contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wanghesong2019/llm-io-normalizer
+Project-URL: Repository, https://github.com/wanghesong2019/llm-io-normalizer
+Project-URL: Issues, https://github.com/wanghesong2019/llm-io-normalizer/issues
+Keywords: llm,model-io,openai-compatible,reasoning,streaming,normalization,judge-model,tested-model,structured-output
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# llm-io-normalizer
+
+`llm-io-normalizer` is a lightweight **Model I/O normalization layer** for OpenAI-compatible LLM calls.
+It is built for applications that call both **tested models** and **judge models** and need a stable result contract instead of provider-specific response parsing.
+
+It normalizes common LLM response differences such as:
+
+- `message.content` vs `message.reasoning`
+- `delta.content` vs `delta.reasoning` / `delta.reasoning_content`
+- `<think>...</think>` reasoning mixed into normal content
+- stream vs non-stream completion behavior
+- successful HTTP responses that contain reasoning but no final answer
+- final JSON extraction from model output
+
+The public contract is intentionally small and stable:
+
+```python
+result.answer_text
+result.reasoning_text
+result.ok
+result.error_type
+result.error_message
+```
+
+Business code should depend on these normalized fields instead of reading raw provider fields directly.
+
+## Install
+
+After publishing to PyPI:
+
+```bash
+pip install llm-io-normalizer
+```
+
+From a local checkout:
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from llm_io_normalizer import LLMGateway, LLMRequest, LLMRole
+
+
+async def main() -> None:
+    gateway = LLMGateway()
+
+    result = await gateway.generate(
+        LLMRequest(
+            role=LLMRole.JUDGE_MODEL,
+            model_name="your-model-name",
+            base_url="https://example.com/v1",
+            api_key="YOUR_API_KEY",
+            messages=[
+                {"role": "system", "content": "You are a strict JSON judge."},
+                {"role": "user", "content": "Return {\"result\": 2}."},
+            ],
+            # Judge models should usually prefer stable non-stream output.
+            stream=False,
+            enable_thinking=False,
+            temperature=0,
+            max_tokens=1024,
+        )
+    )
+
+    result.require_ok()
+    print(result.answer_text)
+
+
+asyncio.run(main())
+```
+
+## Core concepts
+
+### Tested model calls
+
+`LLMRole.TESTED_MODEL` is for the model being evaluated or observed.
+
+Default behavior:
+
+- streams by default unless `stream=False` is provided
+- can collect native reasoning fields from compatible providers
+- can split `<think>...</think>` blocks out of the answer
+- returns clean `answer_text` and separate `reasoning_text`
+- can retry without thinking when the provider returns no final answer
+
+### Judge model calls
+
+`LLMRole.JUDGE_MODEL` is for scoring, evaluation, moderation, ranking, or structured judgment tasks.
+
+Default behavior:
+
+- uses non-stream mode by default unless `stream=True` is provided
+- is designed for stable final output, especially JSON scoring results
+- usually pairs well with `enable_thinking=False` and `temperature=0`
+- marks the call as `ok=False` with `error_type="EMPTY_ANSWER"` when the provider returns reasoning but no final answer
+
+## JSON output helper
+
+```python
+from llm_io_normalizer.normalizers import extract_json_object
+
+obj = extract_json_object('```json\n{"result": 2}\n```')
+assert obj == {"result": 2}
+```
+
+## Examples
+
+The `examples/` directory contains runnable examples for:
+
+- tested-model calls
+- judge-model calls
+- a tested-model → judge-model evaluation pipeline
+
+Use environment variables for provider credentials and endpoints when running examples:
+
+```bash
+export LLM_BASE_URL="https://your-provider.example/v1"
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="your-model-name"
+python examples/judge_model.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+## Release
+
+Recommended PyPI release mode is **Trusted Publishing** from GitHub Actions.
+Configure the PyPI project to trust this repository workflow, then publish a GitHub release tag such as `v0.1.0`.
+
+## Scope
+
+This package is intentionally **not** a full API gateway.
+It does not implement authentication, rate limiting, billing, routing dashboards, or multi-tenant governance.
+Those can be handled by an outer gateway such as Kong, APISIX, Envoy, Portkey, or other infrastructure.
+
+`llm-io-normalizer` focuses on the reusable Python SDK layer:
+
+- Model I/O normalization
+- reasoning / answer separation
+- stream / non-stream fallback
+- tested-model and judge-model call policies
+- unified result/error contract
+- simple JSON object extraction from model output

llm_io_normalizer-0.1.0/src/llm_io_normalizer.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/llm_io_normalizer/__init__.py
+src/llm_io_normalizer/errors.py
+src/llm_io_normalizer/gateway.py
+src/llm_io_normalizer/py.typed
+src/llm_io_normalizer/schemas.py
+src/llm_io_normalizer.egg-info/PKG-INFO
+src/llm_io_normalizer.egg-info/SOURCES.txt
+src/llm_io_normalizer.egg-info/dependency_links.txt
+src/llm_io_normalizer.egg-info/requires.txt
+src/llm_io_normalizer.egg-info/top_level.txt
+src/llm_io_normalizer/adapters/__init__.py
+src/llm_io_normalizer/adapters/openai_compatible.py
+src/llm_io_normalizer/normalizers/__init__.py
+src/llm_io_normalizer/normalizers/json_output.py
+src/llm_io_normalizer/normalizers/reasoning.py
+tests/test_gateway_stream_extraction.py
+tests/test_json_output.py
+tests/test_reasoning_normalizer.py

llm_io_normalizer-0.1.0/src/llm_io_normalizer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llm_io_normalizer-0.1.0/src/llm_io_normalizer.egg-info/requires.txt

@@ -0,0 +1,7 @@
+openai>=1.0.0
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+ruff>=0.6
+build>=1.2

llm_io_normalizer-0.1.0/src/llm_io_normalizer.egg-info/top_level.txt

@@ -0,0 +1 @@
+llm_io_normalizer

llm_io_normalizer-0.1.0/tests/test_gateway_stream_extraction.py

@@ -0,0 +1,17 @@
+from types import SimpleNamespace
+
+from llm_io_normalizer.adapters.openai_compatible import OpenAICompatibleGateway
+
+
+def test_extract_delta_content_and_reasoning_attributes():
+    gateway = OpenAICompatibleGateway()
+    delta = SimpleNamespace(content="answer", reasoning="think", reasoning_content="think2")
+    assert gateway._extract_delta_content(delta) == "answer"
+    assert gateway._extract_delta_reasoning(delta) == "thinkthink2"
+
+
+def test_extract_delta_dict():
+    gateway = OpenAICompatibleGateway()
+    delta = {"content": "answer", "reasoning": "think"}
+    assert gateway._extract_delta_content(delta) == "answer"
+    assert gateway._extract_delta_reasoning(delta) == "think"

llm_io_normalizer-0.1.0/tests/test_json_output.py

@@ -0,0 +1,13 @@
+from llm_io_normalizer.normalizers import extract_json_object
+
+
+def test_extract_json_object_plain():
+    assert extract_json_object('{"结果": 2}') == {"结果": 2}
+
+
+def test_extract_json_object_fenced():
+    assert extract_json_object('```json\n{"结果": 0}\n```') == {"结果": 0}
+
+
+def test_extract_json_object_embedded():
+    assert extract_json_object('分析如下 {"结果": 1} 结束') == {"结果": 1}

llm_io_normalizer-0.1.0/tests/test_reasoning_normalizer.py

@@ -0,0 +1,23 @@
+from llm_io_normalizer.normalizers import normalize_reasoning_answer, split_think_tag
+
+
+def test_split_think_tag():
+    parsed = split_think_tag("<think>plan</think>final")
+    assert parsed is not None
+    assert parsed.reasoning_text == "plan"
+    assert parsed.answer_text == "final"
+    assert parsed.parse_method == "think_tag"
+
+
+def test_native_reasoning_wins():
+    parsed = normalize_reasoning_answer(content_text="final", native_reasoning_text="thought")
+    assert parsed.reasoning_text == "thought"
+    assert parsed.answer_text == "final"
+    assert parsed.parse_method == "native_reasoning"
+
+
+def test_content_only():
+    parsed = normalize_reasoning_answer(content_text="hello")
+    assert parsed.reasoning_text == ""
+    assert parsed.answer_text == "hello"
+    assert parsed.parse_method == "content_only"