llmframe 0.1.0__py3-none-any.whl

llmframe/__init__.py

@@ -0,0 +1,5 @@
+"""llmframe package."""
+
+from .adapters.output import llm
+
+__all__ = ["llm"]

llmframe/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters layer for external integrations."""

llmframe/adapters/input/__init__.py

@@ -0,0 +1 @@
+"""Driving adapters that invoke application use cases."""

llmframe/adapters/output/__init__.py

@@ -0,0 +1,5 @@
+"""Driven adapters that implement output ports."""
+
+from . import llm
+
+__all__ = ["llm"]

llmframe/adapters/output/llm/__init__.py

@@ -0,0 +1,55 @@
+"""Public exports for shared LLM adapters."""
+
+from .llm_adapter import (
+    LlmAdapter,
+    LlmTextCompletionResult,
+    StructuredLlmError,
+    StructuredLlmInvalidJsonError,
+    StructuredLlmJsonCompletionResult,
+    StructuredLlmResponseError,
+)
+from .openai_adapter import (
+    ChatCompletionJsonProtocol,
+    ChatCompletionStructuredProtocol,
+    ChatCompletionTextProtocol,
+    OpenAIClient,
+    OpenAIClientProtocol,
+    OpenAIClientSettings,
+    OpenAILlmProtocol,
+    OpenAIResponseError,
+    OpenAIResponseUsage,
+    ResponseJsonProtocol,
+    ResponseStructuredProtocol,
+    ResponseTextProtocol,
+    build_client,
+    extract_message_content,
+    extract_usage,
+)
+from .usage_tracker import LlmUsageSummary, LlmUsageTrackerConfig, OpenAILlmUsageTracker
+
+__all__ = [
+    "ChatCompletionJsonProtocol",
+    "ChatCompletionStructuredProtocol",
+    "ChatCompletionTextProtocol",
+    "LlmAdapter",
+    "LlmTextCompletionResult",
+    "LlmUsageSummary",
+    "LlmUsageTrackerConfig",
+    "OpenAIClient",
+    "OpenAIClientProtocol",
+    "OpenAIClientSettings",
+    "OpenAILlmProtocol",
+    "OpenAILlmUsageTracker",
+    "OpenAIResponseError",
+    "OpenAIResponseUsage",
+    "ResponseJsonProtocol",
+    "ResponseStructuredProtocol",
+    "ResponseTextProtocol",
+    "StructuredLlmError",
+    "StructuredLlmInvalidJsonError",
+    "StructuredLlmJsonCompletionResult",
+    "StructuredLlmResponseError",
+    "build_client",
+    "extract_message_content",
+    "extract_usage",
+]

llmframe/adapters/output/llm/llm_adapter/__init__.py

@@ -0,0 +1,18 @@
+"""Public exports for the shared LLM adapter."""
+
+from .adapter import LlmAdapter
+from .dto import LlmTextCompletionResult, StructuredLlmJsonCompletionResult
+from .exceptions import (
+    StructuredLlmError,
+    StructuredLlmInvalidJsonError,
+    StructuredLlmResponseError,
+)
+
+__all__ = [
+    "LlmAdapter",
+    "LlmTextCompletionResult",
+    "StructuredLlmError",
+    "StructuredLlmInvalidJsonError",
+    "StructuredLlmJsonCompletionResult",
+    "StructuredLlmResponseError",
+]

llmframe/adapters/output/llm/llm_adapter/adapter.py

@@ -0,0 +1,301 @@
+"""Shared LLM adapter for structured extraction and text generation."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, cast
+
+from llmframe.adapters.output.llm.openai_adapter import extract_usage
+
+from .dto import LlmTextCompletionResult, StructuredLlmJsonCompletionResult
+from .exceptions import StructuredLlmError
+from .logging_utils import build_json_payload_log_extra, build_text_payload_log_extra
+from .response_parser import extract_structured_content, parse_json_object
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from llmframe.adapters.output.llm.openai_adapter import OpenAILlmProtocol, ReasoningEffort
+    from llmframe.adapters.output.persistence import JsonWriterProtocol
+    from llmframe.json_types import JsonValue
+
+    from .protocols import StructuredOutputSchema
+
+LOGGER = logging.getLogger(__name__)
+
+REQUEST_DEBUG_LABEL = "request_payload"
+RESPONSE_TEXT_DEBUG_LABEL = "response_text"
+PARSED_RESPONSE_DEBUG_LABEL = "parsed_response_payload"
+
+
+class LlmAdapter:
+    """Generate structured JSON payloads and plain-text responses."""
+
+    def __init__(
+        self,
+        *,
+        client: OpenAILlmProtocol,
+        model: str,
+        debug_json_writer: JsonWriterProtocol | None = None,
+        debug_json_enabled: bool = False,
+    ) -> None:
+        """Store transport client and runtime configuration."""
+        self._client = client
+        self._model = model
+        self._api_surface = "responses"
+        self._debug_json_writer = debug_json_writer
+        self._debug_json_enabled = debug_json_enabled
+
+    def generate_text(
+        self,
+        *,
+        developer_prompt: str,
+        user_prompt: str,
+        temperature: float | None = None,
+        reasoning_effort: str | None = None,
+    ) -> LlmTextCompletionResult:
+        """Return plain-text content together with token-usage metadata."""
+        inputs = self._build_inputs(developer_prompt=developer_prompt, user_prompt=user_prompt)
+        self._log_json_stage(
+            label=REQUEST_DEBUG_LABEL,
+            payload=self._build_text_request_payload(
+                inputs=inputs,
+                temperature=temperature,
+                reasoning_effort=reasoning_effort,
+            ),
+            message="LLM request payload",
+        )
+        response = self._client.create_response(
+            model=self._model,
+            input_items=inputs,
+            temperature=temperature,
+            reasoning_effort=cast("ReasoningEffort | None", reasoning_effort),
+        )
+        content = extract_structured_content(response)
+        usage = extract_usage(response)
+        self._log_text_stage(
+            label=RESPONSE_TEXT_DEBUG_LABEL,
+            content=content,
+            message="LLM response content",
+        )
+        return LlmTextCompletionResult(content=content, usage=usage)
+
+    def extract_json(
+        self,
+        *,
+        developer_prompt: str,
+        user_prompt: str,
+        response_schema: StructuredOutputSchema | None = None,
+    ) -> StructuredLlmJsonCompletionResult:
+        """Return parsed JSON payload together with token usage metadata."""
+        inputs = self._build_inputs(developer_prompt=developer_prompt, user_prompt=user_prompt)
+        schema_type = self._require_response_schema(response_schema)
+        schema_name = self._schema_name(schema_type)
+        schema = self._build_response_schema(schema_type)
+        self._log_json_stage(
+            label=REQUEST_DEBUG_LABEL,
+            payload=self._build_structured_request_payload(
+                inputs=inputs,
+                schema_name=schema_name,
+                schema=schema,
+            ),
+            message="LLM request payload",
+        )
+
+        response = self._client.create_structured_response(
+            model=self._model,
+            input_items=inputs,
+            json_schema_name=schema_name,
+            schema=schema,
+            temperature=0,
+            reasoning_effort="none",
+        )
+        content = extract_structured_content(response)
+        usage = extract_usage(response)
+        self._log_text_stage(
+            label=RESPONSE_TEXT_DEBUG_LABEL,
+            content=content,
+            message="LLM response content",
+        )
+
+        payload = parse_json_object(content)
+        self._log_json_stage(
+            label=PARSED_RESPONSE_DEBUG_LABEL,
+            payload=payload,
+            message="LLM parsed JSON payload",
+            extra={"payload_keys": list(payload.keys())},
+        )
+        return StructuredLlmJsonCompletionResult(payload=payload, usage=usage)
+
+    def _build_inputs(self, *, developer_prompt: str, user_prompt: str) -> list[dict[str, str]]:
+        """Build structured LLM inputs for the completion request."""
+        return [
+            {"role": "developer", "content": developer_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+    def _build_text_request_payload(
+        self,
+        *,
+        inputs: list[dict[str, str]],
+        temperature: float | None,
+        reasoning_effort: str | None,
+    ) -> dict[str, object]:
+        """Build metadata-safe text request payload details for logging/debug output."""
+        payload: dict[str, object] = {
+            "model": self._model,
+            "input": inputs,
+            "text": {"format": {"type": "text"}},
+        }
+        if temperature is not None:
+            payload["temperature"] = temperature
+        if reasoning_effort is not None:
+            payload["reasoning"] = {"effort": reasoning_effort}
+        return payload
+
+    def _build_structured_request_payload(
+        self,
+        *,
+        inputs: list[dict[str, str]],
+        schema_name: str,
+        schema: dict[str, object],
+    ) -> dict[str, object]:
+        """Build metadata-safe structured request payload details for logging/debug output."""
+        return {
+            "model": self._model,
+            "input": inputs,
+            "reasoning": {"effort": "none"},
+            "temperature": 0,
+            "text": {
+                "format": {
+                    "type": "json_schema",
+                    "name": schema_name,
+                    "strict": True,
+                    "schema": schema,
+                }
+            },
+        }
+
+    def _require_response_schema(self, response_schema: StructuredOutputSchema | None) -> StructuredOutputSchema:
+        """Return the schema required for structured-output requests."""
+        if response_schema is None:
+            msg = "Structured output requests require a response schema"
+            raise StructuredLlmError(msg, suggestion="Pass a Pydantic response schema to the LLM adapter")
+        return response_schema
+
+    def _schema_name(self, schema_type: type[BaseModel]) -> str:
+        """Return a stable schema name for Structured Outputs requests."""
+        return schema_type.__name__
+
+    def _build_response_schema(self, schema_type: type[BaseModel]) -> dict[str, object]:
+        """Return a JSON schema suitable for Structured Outputs requests."""
+        raw_schema = cast("dict[str, object]", schema_type.model_json_schema())
+        return cast("dict[str, object]", self._normalize_schema_node(raw_schema))
+
+    def _normalize_schema_node(self, node: object) -> object:
+        """Normalize one JSON Schema node for OpenAI Structured Outputs."""
+        if isinstance(node, list):
+            return [self._normalize_schema_node(item) for item in node]
+
+        if not isinstance(node, dict):
+            return node
+
+        normalized: dict[str, object] = {}
+        for key, value in node.items():
+            if key == "properties" and isinstance(value, dict):
+                filtered_properties: dict[str, object] = {}
+                for field_name, field_schema in value.items():
+                    if isinstance(field_schema, dict) and field_schema.get("internal") is True:
+                        continue
+                    filtered_properties[field_name] = self._normalize_schema_node(field_schema)
+                normalized[key] = filtered_properties
+                continue
+
+            normalized[key] = self._normalize_schema_node(value)
+
+        if "$ref" in normalized:
+            return {"$ref": normalized["$ref"]}
+
+        properties = normalized.get("properties")
+        if isinstance(properties, dict):
+            normalized["additionalProperties"] = False
+            required_fields = normalized.get("required")
+            if isinstance(required_fields, list):
+                normalized["required"] = [field_name for field_name in required_fields if field_name in properties]
+
+        return normalized
+
+    def _log_json_stage(
+        self,
+        *,
+        label: str,
+        payload: object,
+        message: str,
+        extra: dict[str, object] | None = None,
+    ) -> None:
+        """Write and log JSON-stage metadata without logging raw payload content."""
+        self._write_debug_payload(label=label, payload=payload)
+        payload_extra = build_json_payload_log_extra(payload=payload)
+        if extra is not None:
+            payload_extra.update(extra)
+        self._log_payload_metadata(message=message, extra={"debug_label": label, **payload_extra})
+
+    def _log_text_stage(
+        self,
+        *,
+        label: str,
+        content: str,
+        message: str,
+        extra: dict[str, object] | None = None,
+    ) -> None:
+        """Write and log text-stage metadata without logging raw content."""
+        self._write_debug_payload(label=label, payload={"content": content})
+        payload_extra = build_text_payload_log_extra(content=content)
+        if extra is not None:
+            payload_extra.update(extra)
+        self._log_payload_metadata(message=message, extra={"debug_label": label, **payload_extra})
+
+    def _log_payload_metadata(
+        self,
+        *,
+        message: str,
+        extra: dict[str, object],
+    ) -> None:
+        """Log payload metadata without logging raw payload content."""
+        log_extra: dict[str, object] = {
+            "component": self.__class__.__name__,
+            "model": self._model,
+            "api_surface": self._api_surface,
+        }
+        log_extra.update(extra)
+
+        LOGGER.debug(message, extra=log_extra)
+
+    def _write_debug_payload(self, *, label: str, payload: object) -> None:
+        """Write a labeled debug payload when debug JSON output is enabled."""
+        if not self._debug_json_enabled or self._debug_json_writer is None:
+            return
+
+        try:
+            written_path = self._debug_json_writer.write_json(label=label, payload=cast("JsonValue", payload))
+        except (OSError, TypeError, ValueError) as err:
+            LOGGER.warning(
+                "Failed to write LLM debug payload",
+                exc_info=err,
+                extra={
+                    "component": self.__class__.__name__,
+                    "model": self._model,
+                    "debug_label": label,
+                },
+            )
+            return
+
+        LOGGER.debug(
+            "LLM debug payload written",
+            extra={
+                "component": self.__class__.__name__,
+                "model": self._model,
+                "debug_label": label,
+                "file_path": str(written_path),
+            },
+        )

llmframe/adapters/output/llm/llm_adapter/dto.py

@@ -0,0 +1,26 @@
+"""DTOs returned by the shared LLM adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from llmframe.adapters.output.llm.openai_adapter import OpenAIResponseUsage
+    from llmframe.json_types import JsonValue
+
+
+@dataclass(frozen=True)
+class StructuredLlmJsonCompletionResult:
+    """Structured JSON result plus token-usage metadata."""
+
+    payload: dict[str, JsonValue]
+    usage: OpenAIResponseUsage | None
+
+
+@dataclass(frozen=True)
+class LlmTextCompletionResult:
+    """Plain-text result plus token-usage metadata."""
+
+    content: str
+    usage: OpenAIResponseUsage | None

llmframe/adapters/output/llm/llm_adapter/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception types for the shared LLM adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class StructuredLlmError(Exception):
+    """Base exception for shared LLM adapter failures."""
+
+    message: str
+    suggestion: str | None = None
+
+    def __str__(self) -> str:
+        """Return the user-facing error message."""
+        return self.message
+
+
+class StructuredLlmResponseError(StructuredLlmError):
+    """Raised when an LLM response is missing required content."""
+
+
+class StructuredLlmInvalidJsonError(StructuredLlmError):
+    """Raised when the LLM response cannot be parsed as a JSON object."""

llmframe/adapters/output/llm/llm_adapter/logging_utils.py

@@ -0,0 +1,27 @@
+"""Logging helpers for LLM adapter payload metadata."""
+
+from __future__ import annotations
+
+import json
+
+
+def build_json_payload_log_extra(*, payload: object) -> dict[str, object]:
+    """Return metadata-only logging fields for a JSON-serializable payload."""
+    serialized_payload = json.dumps(payload, ensure_ascii=False, default=str)
+    metadata: dict[str, object] = {
+        "payload_length": len(serialized_payload),
+        "payload_kind": type(payload).__name__,
+        "payload_preview_omitted": True,
+    }
+    if isinstance(payload, dict):
+        metadata["payload_keys"] = sorted(str(key) for key in payload)
+    return metadata
+
+
+def build_text_payload_log_extra(*, content: str) -> dict[str, object]:
+    """Return metadata-only logging fields for a text payload."""
+    return {
+        "payload_length": len(content),
+        "payload_kind": "text",
+        "payload_preview_omitted": True,
+    }

llmframe/adapters/output/llm/llm_adapter/protocols.py

@@ -0,0 +1,14 @@
+"""Narrow type alias used by the shared LLM adapter."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+from pydantic import BaseModel
+
+StructuredOutputSchema: TypeAlias = type[BaseModel]
+
+
+__all__ = [
+    "StructuredOutputSchema",
+]

llmframe/adapters/output/llm/llm_adapter/response_parser.py

@@ -0,0 +1,38 @@
+"""Response parsing helpers for structured LLM outputs."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, cast
+
+from llmframe.adapters.output.llm.openai_adapter import (
+    OpenAIResponseError,
+    extract_message_content,
+)
+
+from .exceptions import StructuredLlmInvalidJsonError, StructuredLlmResponseError
+
+if TYPE_CHECKING:
+    from llmframe.json_types import JsonValue
+
+
+def extract_structured_content(response: object) -> str:
+    """Extract textual content from an OpenAI response object."""
+    try:
+        return extract_message_content(response)
+    except OpenAIResponseError as err:
+        msg = "LLM response is missing content or has an invalid shape"
+        raise StructuredLlmResponseError(msg, suggestion=str(err)) from err
+
+
+def parse_json_object(content: str) -> dict[str, JsonValue]:
+    """Parse model content and require a top-level JSON object result."""
+    try:
+        payload = json.loads(content)
+    except json.JSONDecodeError as err:
+        msg = "LLM returned invalid JSON payload"
+        raise StructuredLlmInvalidJsonError(msg, suggestion="Inspect the model output and prompts") from err
+    if not isinstance(payload, dict):
+        msg = "LLM payload must be a JSON object"
+        raise StructuredLlmInvalidJsonError(msg, suggestion="Ensure the prompt requests a top-level JSON object")
+    return cast("dict[str, JsonValue]", payload)

llmframe/adapters/output/llm/openai_adapter/__init__.py

@@ -0,0 +1,47 @@
+"""Public exports for the shared OpenAI client and helpers."""
+
+from .client import build_client
+from .dto import (
+    OpenAIClientSettings,
+    OpenAIResponseError,
+    OpenAIResponseUsage,
+)
+from .parsing import (
+    extract_message_content,
+    extract_usage,
+)
+from .transport import (
+    ChatCompletionJsonProtocol,
+    ChatCompletionStructuredProtocol,
+    ChatCompletionTextProtocol,
+    OpenAIClient,
+    OpenAIClientProtocol,
+    OpenAILlmProtocol,
+    OpenAIRequestConfigError,
+    ReasoningEffort,
+    ResponseJsonProtocol,
+    ResponseStructuredProtocol,
+    ResponseTextProtocol,
+    build_structured_schema_definition,
+)
+
+__all__ = [
+    "ChatCompletionJsonProtocol",
+    "ChatCompletionStructuredProtocol",
+    "ChatCompletionTextProtocol",
+    "OpenAIClient",
+    "OpenAIClientProtocol",
+    "OpenAIClientSettings",
+    "OpenAILlmProtocol",
+    "OpenAIRequestConfigError",
+    "OpenAIResponseError",
+    "OpenAIResponseUsage",
+    "ReasoningEffort",
+    "ResponseJsonProtocol",
+    "ResponseStructuredProtocol",
+    "ResponseTextProtocol",
+    "build_client",
+    "build_structured_schema_definition",
+    "extract_message_content",
+    "extract_usage",
+]

llmframe/adapters/output/llm/openai_adapter/client.py

@@ -0,0 +1,41 @@
+"""Helpers for constructing the shared OpenAI transport client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+from openai import OpenAI
+
+from .transport import OpenAIClient
+
+if TYPE_CHECKING:
+    from llmframe.adapters.output.persistence import JsonWriterProtocol
+
+    from .dto import OpenAIClientSettings
+
+
+def build_client(
+    settings: OpenAIClientSettings,
+    *,
+    debug_json_writer: JsonWriterProtocol | None = None,
+    debug_json_enabled: bool = False,
+) -> OpenAIClient:
+    """Build an ``OpenAIClient`` from explicit settings."""
+    timeout = httpx.Timeout(settings.timeout_seconds)
+    http_client = httpx.Client(
+        verify=settings.verify_ssl,
+        timeout=timeout,
+    )
+    sdk_client = OpenAI(
+        base_url=settings.base_url,
+        api_key=settings.api_key,
+        http_client=http_client,
+    )
+    return OpenAIClient(
+        sdk_client=sdk_client,
+        max_retries=settings.max_retries,
+        backoff_factor=settings.backoff_factor,
+        debug_json_writer=debug_json_writer,
+        debug_json_enabled=debug_json_enabled,
+    )

llmframe/adapters/output/llm/openai_adapter/dto.py

@@ -0,0 +1,32 @@
+"""Public DTOs and exceptions for shared OpenAI response handling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .transport import DEFAULT_BACKOFF_FACTOR, DEFAULT_MAX_RETRIES
+
+
+class OpenAIResponseError(ValueError):
+    """Raised when the OpenAI response shape is invalid."""
+
+
+@dataclass(frozen=True)
+class OpenAIClientSettings:
+    """Configuration for creating an OpenAI transport client."""
+
+    base_url: str
+    api_key: str
+    max_retries: int = DEFAULT_MAX_RETRIES
+    backoff_factor: float = DEFAULT_BACKOFF_FACTOR
+    verify_ssl: bool = True
+    timeout_seconds: float = 30.0
+
+
+@dataclass(frozen=True)
+class OpenAIResponseUsage:
+    """Normalized token usage metadata extracted from an OpenAI response."""
+
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int | None

llmframe/adapters/output/llm/openai_adapter/parsing/__init__.py

@@ -0,0 +1,6 @@
+"""Public parsing helpers for OpenAI response payloads."""
+
+from .message_content import extract_message_content
+from .usage import extract_usage
+
+__all__ = ["extract_message_content", "extract_usage"]