structured-llm 0.1.0__py3-none-any.whl

structured_llm/__init__.py

@@ -0,0 +1,22 @@
+from .client import StructuredClient
+from .errors import (
+    ProviderError,
+    StructuredLLMError,
+    StructuredParseError,
+    StructuredValidationError,
+    UnsupportedSchemaError,
+)
+from .parser import parse_structured_text
+from .schema import build_schema_spec
+
+__all__ = [
+    "ProviderError",
+    "StructuredClient",
+    "StructuredLLMError",
+    "StructuredParseError",
+    "StructuredValidationError",
+    "UnsupportedSchemaError",
+    "build_schema_spec",
+    "parse_structured_text",
+]
+

structured_llm/client.py

@@ -0,0 +1,459 @@
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import sys
+from typing import Any, Literal, TypeVar, overload
+
+from .errors import ProviderError, StructuredLLMError, StructuredValidationError
+from .parser import parse_structured_text
+from .schema import SchemaSpec, build_schema_spec
+
+
+Mode = Literal["auto", "native", "prompt"]
+Endpoint = Literal["chat", "responses"]
+T = TypeVar("T")
+
+
+class StructuredClient:
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        mode: Mode = "prompt",
+        endpoint: Endpoint = "chat",
+        max_retries: int = 1,
+        debug: bool = False,
+        openai_client: Any | None = None,
+        async_openai_client: Any | None = None,
+    ) -> None:
+        if mode not in {"auto", "native", "prompt"}:
+            raise ValueError("mode must be 'auto', 'native', or 'prompt'")
+        if endpoint not in {"chat", "responses"}:
+            raise ValueError("endpoint must be 'chat' or 'responses'")
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+
+        self.model = model
+        self.api_key = _value_or_env(api_key, "OPENAI_API_KEY")
+        self.base_url = _value_or_env(base_url, "OPENAI_BASE_URL")
+        self.mode = mode
+        self.endpoint = endpoint
+        self.max_retries = max_retries
+        self.debug = debug
+        self._client = openai_client
+        self._async_client = async_openai_client
+
+    @overload
+    def run(
+        self,
+        prompt: str,
+        schema: type[T],
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> T: ...
+
+    @overload
+    def run(
+        self,
+        prompt: str,
+        schema: Any,
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> Any: ...
+
+    def run(
+        self,
+        prompt: str,
+        schema: Any,
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> Any:
+        spec = build_schema_spec(schema)
+        raw_text = self._complete(prompt, spec, system=system, **model_options)
+        return self._parse_with_retry(raw_text, spec, prompt=prompt, system=system, model_options=model_options)
+
+    @overload
+    async def arun(
+        self,
+        prompt: str,
+        schema: type[T],
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> T: ...
+
+    @overload
+    async def arun(
+        self,
+        prompt: str,
+        schema: Any,
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> Any: ...
+
+    async def arun(
+        self,
+        prompt: str,
+        schema: Any,
+        *,
+        system: str | None = None,
+        **model_options: Any,
+    ) -> Any:
+        spec = build_schema_spec(schema)
+        raw_text = await self._acomplete(prompt, spec, system=system, **model_options)
+        return await self._aparse_with_retry(
+            raw_text,
+            spec,
+            prompt=prompt,
+            system=system,
+            model_options=model_options,
+        )
+
+    @overload
+    def parse(self, text: str, schema: type[T], *, repair: bool = True) -> T: ...
+
+    @overload
+    def parse(self, text: str, schema: Any, *, repair: bool = True) -> Any: ...
+
+    def parse(self, text: str, schema: Any, *, repair: bool = True) -> Any:
+        return parse_structured_text(text, schema, repair=repair)
+
+    def _complete(
+        self,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        **model_options: Any,
+    ) -> str:
+        if self.mode == "prompt":
+            return self._call_prompt(prompt, spec, system=system, **model_options)
+        if self.mode == "native":
+            return self._call_native(prompt, spec, system=system, **model_options)
+        try:
+            return self._call_native(prompt, spec, system=system, **model_options)
+        except ProviderError as exc:
+            if not _looks_like_unsupported_native(exc):
+                raise
+            return self._call_prompt(prompt, spec, system=system, **model_options)
+
+    async def _acomplete(
+        self,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        **model_options: Any,
+    ) -> str:
+        if self.mode == "prompt":
+            return await self._acall_prompt(prompt, spec, system=system, **model_options)
+        if self.mode == "native":
+            return await self._acall_native(prompt, spec, system=system, **model_options)
+        try:
+            return await self._acall_native(prompt, spec, system=system, **model_options)
+        except ProviderError as exc:
+            if not _looks_like_unsupported_native(exc):
+                raise
+            return await self._acall_prompt(prompt, spec, system=system, **model_options)
+
+    def _parse_with_retry(
+        self,
+        raw_text: str,
+        spec: SchemaSpec,
+        *,
+        prompt: str,
+        system: str | None,
+        model_options: dict[str, Any],
+    ) -> Any:
+        try:
+            return parse_structured_text(raw_text, spec)
+        except StructuredValidationError as exc:
+            if self.max_retries <= 0:
+                raise
+            retry_prompt = _retry_prompt(prompt, spec, exc)
+            retry_text = self._call_prompt(retry_prompt, spec, system=system, **model_options)
+            return parse_structured_text(retry_text, spec)
+
+    async def _aparse_with_retry(
+        self,
+        raw_text: str,
+        spec: SchemaSpec,
+        *,
+        prompt: str,
+        system: str | None,
+        model_options: dict[str, Any],
+    ) -> Any:
+        try:
+            return parse_structured_text(raw_text, spec)
+        except StructuredValidationError as exc:
+            if self.max_retries <= 0:
+                raise
+            retry_prompt = _retry_prompt(prompt, spec, exc)
+            retry_text = await self._acall_prompt(retry_prompt, spec, system=system, **model_options)
+            return parse_structured_text(retry_text, spec)
+
+    def _call_native(self, prompt: str, spec: SchemaSpec, *, system: str | None, **model_options: Any) -> str:
+        client = self._sync_client()
+        try:
+            response = self._invoke_sync(client, prompt, spec, system=system, native=True, **model_options)
+            raw_text = _extract_response_text(response)
+            self._debug_raw_output(raw_text)
+            return raw_text
+        except StructuredLLMError:
+            raise
+        except Exception as exc:
+            raise ProviderError("Provider native structured output call failed", cause=exc) from exc
+
+    def _call_prompt(self, prompt: str, spec: SchemaSpec, *, system: str | None, **model_options: Any) -> str:
+        client = self._sync_client()
+        prompt = _prompt_with_schema(prompt, spec)
+        try:
+            response = self._invoke_sync(client, prompt, spec, system=system, native=False, **model_options)
+            raw_text = _extract_response_text(response)
+            self._debug_raw_output(raw_text)
+            return raw_text
+        except StructuredLLMError:
+            raise
+        except Exception as exc:
+            raise ProviderError("Provider prompt structured output call failed", cause=exc) from exc
+
+    async def _acall_native(self, prompt: str, spec: SchemaSpec, *, system: str | None, **model_options: Any) -> str:
+        client = self._async_openai_client()
+        try:
+            response = await self._invoke_async(client, prompt, spec, system=system, native=True, **model_options)
+            raw_text = _extract_response_text(response)
+            self._debug_raw_output(raw_text)
+            return raw_text
+        except StructuredLLMError:
+            raise
+        except Exception as exc:
+            raise ProviderError("Provider native structured output call failed", cause=exc) from exc
+
+    async def _acall_prompt(self, prompt: str, spec: SchemaSpec, *, system: str | None, **model_options: Any) -> str:
+        client = self._async_openai_client()
+        prompt = _prompt_with_schema(prompt, spec)
+        try:
+            response = await self._invoke_async(client, prompt, spec, system=system, native=False, **model_options)
+            raw_text = _extract_response_text(response)
+            self._debug_raw_output(raw_text)
+            return raw_text
+        except StructuredLLMError:
+            raise
+        except Exception as exc:
+            raise ProviderError("Provider prompt structured output call failed", cause=exc) from exc
+
+    def _invoke_sync(
+        self,
+        client: Any,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        native: bool,
+        **model_options: Any,
+    ) -> Any:
+        if self.endpoint == "responses":
+            kwargs = self._responses_kwargs(prompt, spec, system=system, native=native, **model_options)
+            self._debug_request("responses.create", kwargs)
+            return client.responses.create(**kwargs)
+        kwargs = self._chat_kwargs(prompt, spec, system=system, native=native, **model_options)
+        self._debug_request("chat.completions.create", kwargs)
+        return client.chat.completions.create(**kwargs)
+
+    async def _invoke_async(
+        self,
+        client: Any,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        native: bool,
+        **model_options: Any,
+    ) -> Any:
+        if self.endpoint == "responses":
+            kwargs = self._responses_kwargs(prompt, spec, system=system, native=native, **model_options)
+            self._debug_request("responses.create", kwargs)
+            return await _maybe_await(client.responses.create(**kwargs))
+        kwargs = self._chat_kwargs(prompt, spec, system=system, native=native, **model_options)
+        self._debug_request("chat.completions.create", kwargs)
+        return await _maybe_await(client.chat.completions.create(**kwargs))
+
+    def _chat_kwargs(
+        self,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        native: bool,
+        **model_options: Any,
+    ) -> dict[str, Any]:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        kwargs = {"model": self.model, "messages": messages, **model_options}
+        if native:
+            kwargs["response_format"] = _chat_response_format(spec)
+        return kwargs
+
+    def _responses_kwargs(
+        self,
+        prompt: str,
+        spec: SchemaSpec,
+        *,
+        system: str | None,
+        native: bool,
+        **model_options: Any,
+    ) -> dict[str, Any]:
+        input_text = prompt if system is None else f"{system}\n\n{prompt}"
+        kwargs = {"model": self.model, "input": input_text, **model_options}
+        if native:
+            kwargs["text"] = {"format": _responses_text_format(spec)}
+        return kwargs
+
+    def _sync_client(self) -> Any:
+        if self._client is None:
+            try:
+                from openai import OpenAI
+            except ImportError as exc:  # pragma: no cover - dependency is declared
+                raise ProviderError("openai package is required for provider calls", cause=exc) from exc
+            self._client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+        return self._client
+
+    def _async_openai_client(self) -> Any:
+        if self._async_client is None:
+            try:
+                from openai import AsyncOpenAI
+            except ImportError as exc:  # pragma: no cover - dependency is declared
+                raise ProviderError("openai package is required for provider calls", cause=exc) from exc
+            self._async_client = AsyncOpenAI(api_key=self.api_key, base_url=self.base_url)
+        return self._async_client
+
+    def _debug_request(self, endpoint: str, kwargs: dict[str, Any]) -> None:
+        if not self.debug:
+            return
+        print(f"[structured-llm debug] request {endpoint}", file=sys.stderr)
+        print(json.dumps(kwargs, ensure_ascii=False, indent=2, default=repr), file=sys.stderr)
+
+    def _debug_raw_output(self, raw_text: str) -> None:
+        if not self.debug:
+            return
+        print("[structured-llm debug] raw output", file=sys.stderr)
+        print(raw_text, file=sys.stderr)
+
+
+def _chat_response_format(spec: SchemaSpec) -> dict[str, Any]:
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": spec.name,
+            "strict": True,
+            "schema": spec.native_json_schema,
+        },
+    }
+
+
+def _responses_text_format(spec: SchemaSpec) -> dict[str, Any]:
+    return {
+        "type": "json_schema",
+        "name": spec.name,
+        "strict": True,
+        "schema": spec.native_json_schema,
+    }
+
+
+def _prompt_with_schema(prompt: str, spec: SchemaSpec) -> str:
+    return (
+        f"{prompt.rstrip()}\n\n"
+        "Return a JSON value that matches this output format:\n"
+        f"{spec.prompt_schema}\n\n"
+        "Return only the JSON value. Do not include markdown fences, explanations, or extra text."
+    )
+
+
+def _retry_prompt(prompt: str, spec: SchemaSpec, exc: StructuredValidationError) -> str:
+    return (
+        f"{prompt.rstrip()}\n\n"
+        "The previous response did not match the required JSON schema.\n"
+        f"Validation error:\n{exc.validation_error}\n\n"
+        "Return corrected JSON only, matching this schema:\n"
+        f"{spec.prompt_schema}"
+    )
+
+
+def _looks_like_unsupported_native(exc: ProviderError) -> bool:
+    text = f"{exc} {exc.cause}".lower()
+    markers = [
+        "response_format",
+        "json_schema",
+        "unsupported",
+        "not supported",
+        "unknown parameter",
+        "invalid parameter",
+        "extra fields not permitted",
+    ]
+    return any(marker in text for marker in markers)
+
+
+def _value_or_env(value: str | None, env_name: str) -> str | None:
+    if value is not None:
+        return value
+    return os.environ.get(env_name)
+
+
+def _extract_response_text(response: Any) -> str:
+    if isinstance(response, str):
+        return response
+    output_text = _get_attr_or_item(response, "output_text")
+    if isinstance(output_text, str):
+        return output_text
+
+    choices = _get_attr_or_item(response, "choices")
+    if choices:
+        message = _get_attr_or_item(choices[0], "message")
+        content = _get_attr_or_item(message, "content")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            return "".join(
+                part.get("text", "") if isinstance(part, dict) else str(part)
+                for part in content
+            )
+
+    output = _get_attr_or_item(response, "output")
+    if output:
+        texts: list[str] = []
+        for item in output:
+            content = _get_attr_or_item(item, "content")
+            if not content:
+                continue
+            for part in content:
+                text = _get_attr_or_item(part, "text")
+                if isinstance(text, str):
+                    texts.append(text)
+        if texts:
+            return "".join(texts)
+
+    raise ProviderError("Provider response did not contain text output")
+
+
+def _get_attr_or_item(obj: Any, key: str) -> Any:
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj.get(key)
+    return getattr(obj, key, None)
+
+
+async def _maybe_await(value: Any) -> Any:
+    if inspect.isawaitable(value):
+        return await value
+    return value

structured_llm/errors.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class StructuredLLMError(Exception):
+    """Base exception for structured_llm."""
+
+
+class UnsupportedSchemaError(StructuredLLMError):
+    """Raised when a Python type cannot be converted into a usable schema."""
+
+
+class ProviderError(StructuredLLMError):
+    """Raised when the model provider call fails."""
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class StructuredParseError(StructuredLLMError):
+    """Raised when no JSON value can be extracted from model output."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        raw_text: str,
+        schema_name: str,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.raw_text = raw_text
+        self.schema_name = schema_name
+        self.cause = cause
+
+
+class StructuredValidationError(StructuredLLMError):
+    """Raised when extracted JSON does not validate against the target schema."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        raw_text: str,
+        schema_name: str,
+        validation_error: Any,
+    ) -> None:
+        super().__init__(message)
+        self.raw_text = raw_text
+        self.schema_name = schema_name
+        self.validation_error = validation_error
+

structured_llm/parser.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, TypeVar, overload
+
+from pydantic import ValidationError
+
+from .errors import StructuredParseError, StructuredValidationError
+from .schema import SchemaSpec, build_schema_spec
+
+
+_FENCED_JSON_RE = re.compile(r"```(?:json|JSON)?\s*(.*?)```", re.DOTALL)
+_TRAILING_COMMA_RE = re.compile(r",(\s*[}\]])")
+T = TypeVar("T")
+
+
+@overload
+def parse_structured_text(
+    text: str,
+    schema: type[T],
+    *,
+    repair: bool = True,
+    schema_name: str | None = None,
+) -> T: ...
+
+
+@overload
+def parse_structured_text(
+    text: str,
+    schema: Any,
+    *,
+    repair: bool = True,
+    schema_name: str | None = None,
+) -> Any: ...
+
+
+def parse_structured_text(
+    text: str,
+    schema: Any,
+    *,
+    repair: bool = True,
+    schema_name: str | None = None,
+) -> Any:
+    spec = schema if isinstance(schema, SchemaSpec) else build_schema_spec(schema, name=schema_name)
+    value = _extract_json_value(text, repair=repair, schema_name=spec.name)
+    try:
+        return spec.adapter.validate_python(value)
+    except ValidationError as exc:
+        raise StructuredValidationError(
+            f"Response did not match schema {spec.name}",
+            raw_text=text,
+            schema_name=spec.name,
+            validation_error=exc,
+        ) from exc
+
+
+def _extract_json_value(text: str, *, repair: bool, schema_name: str) -> Any:
+    candidates = _candidate_json_strings(text)
+    last_error: BaseException | None = None
+
+    for candidate in candidates:
+        for variant in _repair_variants(candidate) if repair else (candidate,):
+            try:
+                return json.loads(variant)
+            except json.JSONDecodeError as exc:
+                last_error = exc
+
+    raise StructuredParseError(
+        f"No JSON value could be extracted for schema {schema_name}",
+        raw_text=text,
+        schema_name=schema_name,
+        cause=last_error,
+    )
+
+
+def _candidate_json_strings(text: str) -> list[str]:
+    stripped = text.strip()
+    candidates: list[str] = []
+    if stripped:
+        candidates.append(stripped)
+
+    for match in _FENCED_JSON_RE.finditer(text):
+        block = match.group(1).strip()
+        if block:
+            candidates.append(block)
+
+    extracted = _first_balanced_json(text)
+    if extracted and extracted not in candidates:
+        candidates.append(extracted)
+
+    return candidates
+
+
+def _repair_variants(candidate: str) -> tuple[str, ...]:
+    stripped = candidate.strip()
+    no_trailing_commas = _TRAILING_COMMA_RE.sub(r"\1", stripped)
+    variants = [stripped]
+    if no_trailing_commas != stripped:
+        variants.append(no_trailing_commas)
+    return tuple(dict.fromkeys(variants))
+
+
+def _first_balanced_json(text: str) -> str | None:
+    for start, char in enumerate(text):
+        if char not in "{[":
+            continue
+        result = _balanced_from(text, start)
+        if result is not None:
+            return result
+    return None
+
+
+def _balanced_from(text: str, start: int) -> str | None:
+    opener = text[start]
+    closer = "}" if opener == "{" else "]"
+    stack = [closer]
+    in_string = False
+    escape = False
+
+    for idx in range(start + 1, len(text)):
+        char = text[idx]
+        if in_string:
+            if escape:
+                escape = False
+            elif char == "\\":
+                escape = True
+            elif char == '"':
+                in_string = False
+            continue
+
+        if char == '"':
+            in_string = True
+        elif char in "{[":
+            stack.append("}" if char == "{" else "]")
+        elif char in "}]":
+            if not stack or char != stack[-1]:
+                return None
+            stack.pop()
+            if not stack:
+                return text[start : idx + 1]
+
+    return None

structured_llm/schema.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, TypeAdapter
+
+from .errors import UnsupportedSchemaError
+
+
+@dataclass(frozen=True)
+class SchemaSpec:
+    name: str
+    adapter: TypeAdapter[Any]
+    json_schema: dict[str, Any]
+    native_json_schema: dict[str, Any]
+    prompt_schema: str
+
+
+def build_schema_spec(schema: Any, *, name: str | None = None) -> SchemaSpec:
+    try:
+        adapter = TypeAdapter(schema)
+        json_schema = adapter.json_schema()
+    except Exception as exc:  # pragma: no cover - exact pydantic errors vary
+        raise UnsupportedSchemaError(f"Unsupported schema: {schema!r}") from exc
+
+    schema_name = _schema_name(schema, name)
+    prompt_schema = render_prompt_schema(json_schema)
+    return SchemaSpec(
+        name=schema_name,
+        adapter=adapter,
+        json_schema=json_schema,
+        native_json_schema=_to_strict_json_schema(json_schema),
+        prompt_schema=prompt_schema,
+    )
+
+
+def render_prompt_schema(json_schema: dict[str, Any]) -> str:
+    defs = json_schema.get("$defs", {})
+    return _render_type(json_schema, defs, set())
+
+
+def _schema_name(schema: Any, explicit: str | None) -> str:
+    if explicit:
+        raw = explicit
+    elif isinstance(schema, type):
+        raw = schema.__name__
+    else:
+        raw = getattr(schema, "__name__", "structured_output")
+    name = re.sub(r"[^a-zA-Z0-9_-]+", "_", raw).strip("_") or "structured_output"
+    return name[:64]
+
+
+def _render_type(schema: dict[str, Any], defs: dict[str, Any], seen: set[str]) -> str:
+    if "$ref" in schema:
+        ref_name = schema["$ref"].rsplit("/", 1)[-1]
+        if ref_name in seen:
+            return ref_name
+        target = defs.get(ref_name)
+        if not isinstance(target, dict):
+            return ref_name
+        return _render_type(target, defs, {*seen, ref_name})
+
+    if "const" in schema:
+        return repr(schema["const"]).replace("'", '"')
+
+    if "enum" in schema:
+        return " or ".join(repr(item).replace("'", '"') for item in schema["enum"])
+
+    if "anyOf" in schema:
+        return " or ".join(_render_type(item, defs, seen) for item in schema["anyOf"])
+
+    if "oneOf" in schema:
+        return " or ".join(_render_type(item, defs, seen) for item in schema["oneOf"])
+
+    schema_type = schema.get("type")
+    if isinstance(schema_type, list):
+        return " or ".join(_render_type({**schema, "type": item}, defs, seen) for item in schema_type)
+
+    if schema_type == "object" or "properties" in schema:
+        properties = schema.get("properties", {})
+        required = set(schema.get("required", []))
+        if not properties:
+            return "object"
+        lines = ["{"]
+        for key, value in properties.items():
+            metadata = []
+            if key not in required:
+                metadata.append("optional")
+            description = _field_description(value)
+            if description:
+                metadata.append(description)
+            suffix = f" ({'; '.join(metadata)})" if metadata else ""
+            rendered = _render_type(value, defs, seen)
+            lines.append(f"  {key}: {rendered}{suffix},")
+        lines.append("}")
+        return "\n".join(lines)
+
+    if schema_type == "array":
+        item_schema = schema.get("items", {})
+        return f"[{_render_type(item_schema, defs, seen)}]"
+
+    if schema_type == "string":
+        return "string"
+    if schema_type == "integer":
+        return "int"
+    if schema_type == "number":
+        return "float"
+    if schema_type == "boolean":
+        return "bool"
+    if schema_type == "null":
+        return "null"
+
+    return "any"
+
+
+def _field_description(schema: dict[str, Any]) -> str | None:
+    description = schema.get("description")
+    if not isinstance(description, str):
+        return None
+    return " ".join(description.split())
+
+
+def _to_strict_json_schema(schema: Any) -> Any:
+    if isinstance(schema, list):
+        return [_to_strict_json_schema(item) for item in schema]
+    if not isinstance(schema, dict):
+        return schema
+
+    strict = {key: _to_strict_json_schema(value) for key, value in schema.items()}
+
+    if "$defs" in strict and isinstance(strict["$defs"], dict):
+        strict["$defs"] = {
+            key: _to_strict_json_schema(value)
+            for key, value in strict["$defs"].items()
+        }
+
+    properties = strict.get("properties")
+    if isinstance(properties, dict):
+        strict["additionalProperties"] = False
+        strict["required"] = list(properties.keys())
+
+    return strict
+
+
+def is_pydantic_model(schema: Any) -> bool:
+    return isinstance(schema, type) and issubclass(schema, BaseModel)
+
+
+def is_enum(schema: Any) -> bool:
+    return isinstance(schema, type) and issubclass(schema, Enum)

structured_llm-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: structured-llm
+Version: 0.1.0
+Summary: Lightweight structured output runtime for Python LLM calls.
+Author: structured-llm contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.2.2
+Description-Content-Type: text/markdown
+
+# structured-llm
+
+一个轻量的 Python 结构化输出运行时。
+
+它直接使用 Pydantic 类型作为 schema，不需要 `.baml` 文件、CLI、代码生成，也不需要额外的运行时编译器。默认行为是 BAML 风格的「output format prompt + 本地 JSON 提取/轻量修复 + Pydantic 校验」，因此不依赖特定供应商是否支持 `response_format`。
+
+## 安装依赖
+
+普通运行依赖：
+
+```bash
+uv sync --no-config --default-index https://pypi.org/simple
+```
+
+开发依赖安装在 `dev` dependency group 中，包括 `pytest`、`pytest-asyncio`、`ruff`、`mypy`：
+
+```bash
+uv sync --group dev --no-config --default-index https://pypi.org/simple
+```
+
+如果需要新增开发工具依赖：
+
+```bash
+uv add <package> --group dev --no-config --default-index https://pypi.org/simple
+```
+
+## 使用示例
+
+```python
+from pydantic import BaseModel, Field
+from structured_llm import StructuredClient
+
+
+class Receipt(BaseModel):
+    merchant: str = Field(description="商户或店铺名称")
+    total: float = Field(description="收据最终支付总金额")
+
+
+client = StructuredClient(model="gpt-4o-mini", debug=True)
+receipt = client.run("Extract the receipt: Coffee $4.50", Receipt)
+
+print(receipt.merchant)
+print(receipt.total)
+```
+
+默认 OpenAI-compatible provider 会从 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 读取配置；如果代码里显式传入 `api_key` 或 `base_url`，会优先使用显式参数。`examples/receipt_extraction.py` 会通过 `python-dotenv` 自动加载本地 `.env`。
+
+`Field(description=...)` 会渲染到默认 output format prompt。`debug=True` 会把传给 OpenAI-compatible SDK 的 request payload 和模型解析前的原始输出打印到 stderr。默认不会发送 `response_format`；只有显式设置 `mode="native"` 或 `mode="auto"` 时才会尝试 provider-native structured output。
+
+只解析已有的 LLM 文本输出：
+
+```python
+raw = """
+```json
+{"merchant": "Coffee Shop", "total": 4.5}
+```
+"""
+
+receipt = client.parse(raw, Receipt)
+```
+
+## 开发命令
+
+运行测试：
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 uv run --no-config --default-index https://pypi.org/simple --group dev python -m pytest -p no:cacheprovider
+```
+
+运行 Ruff：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev ruff check .
+```
+
+运行 mypy：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev mypy structured_llm
+```
+
+## 当前范围
+
+- 支持同步调用：`StructuredClient.run(...)`
+- 支持异步调用：`StructuredClient.arun(...)`
+- 支持本地解析：`StructuredClient.parse(...)`
+- 支持 Pydantic `BaseModel`、`list[...]`、`dict[...]`、`Literal`、`Enum` 等 `TypeAdapter` 可处理的类型
+- 暂不支持流式 partial object、多 provider 内置适配、BAML DSL/codegen

structured_llm-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+structured_llm/__init__.py,sha256=5PF_0CFfAlyKzwBxmYrUw5_A52yXfa7sIzPEzOKzE2Y,501
+structured_llm/client.py,sha256=4MeToTVi-GA4eeJh3gZ_BJrrb0fEvrjdbFwjX3z6lmE,15601
+structured_llm/errors.py,sha256=5dRCGBAG9DwXAAaxszhUXfahXaiYwwECAO8bNbBicho,1399
+structured_llm/parser.py,sha256=B5UgSGVPT9zcUupO4_UmrCekU7xFPKf0rD59Qw6Um3I,3811
+structured_llm/schema.py,sha256=B9RpDsOWd6wLGnfu4u0BkeWSg5VaxwDrWvtxRSUnXF0,4830
+structured_llm-0.1.0.dist-info/METADATA,sha256=1QKbDGfBsSaDY5fED1550ApRQc6R65kSiGA2z91gzkk,3157
+structured_llm-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+structured_llm-0.1.0.dist-info/RECORD,,

structured_llm-0.1.0.dist-info/WHEEL

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