openaivec 0.12.5__py3-none-any.whl → 1.0.10__py3-none-any.whl

openaivec/_schema/infer.py

@@ -0,0 +1,340 @@
+"""Internal schema inference & dynamic model materialization utilities.
+
+This (non-public) module converts a small *representative* sample of free‑text
+examples plus an *instructions* statement into:
+
+1. A vetted hierarchical object specification (``ObjectSpec``) whose recursively
+     defined ``fields`` (``FieldSpec``) capture reliably extractable signals.
+2. A reusable, self‑contained extraction prompt (``inference_prompt``) that
+     freezes the agreed schema contract (no additions / renames / omissions).
+3. A dynamically generated Pydantic model mirroring the hierarchical schema,
+     enabling immediate typed parsing with the OpenAI Responses API.
+4. A ``PreparedTask`` wrapper (``InferredSchema.task``) for downstream batched
+     responses / structured extraction flows in pandas or Spark.
+
+Core goals:
+* Minimize manual, subjective schema design iterations.
+* Enforce objective naming / typing / enum rules early (guard rails rather than
+    after‑the‑fact cleaning).
+* Provide deterministic reusability: the same prompt + model yield stable field
+    ordering & types for analytics or feature engineering.
+* Avoid outcome / target label leakage in predictive (feature engineering)
+    contexts by explicitly excluding direct target restatements.
+
+This module is intentionally **internal** (``__all__ = []``). Public users
+should interact through higher‑level batch APIs once a schema has been inferred.
+
+Design constraints (updated):
+* Root: single ``ObjectSpec`` (UpperCamelCase name) containing one or more fields.
+* Field types: string | integer | float | boolean | enum | object |
+    string_array | integer_array | float_array | boolean_array | enum_array | object_array
+* Arrays are homogeneous lists of their base type.
+* Nested objects / arrays of objects are allowed when semantically cohesive; keep
+    depth shallow and avoid gratuitous nesting.
+* Enumerations use ``enum_spec`` with explicit ``name`` (UpperCamelCase) and 1–24
+    raw label values (project constant). Values collapse by uppercasing; order not guaranteed.
+* Field names: lower_snake_case; unique per containing object.
+* Boolean names: affirmative 'is_' prefix.
+* Numeric (integer/float) names encode unit / measure suffix (e.g. *_count, *_ratio, *_ms).
+* Validation retries ensure a structurally coherent suggestion before returning.
+
+Example (conceptual):
+        from openai import OpenAI
+        client = OpenAI()
+        inferer = SchemaInferer(client=client, model_name="gpt-4.1-mini")
+        schema = inferer.infer_schema(
+                SchemaInferenceInput(
+                        examples=["Order #123 delayed due to weather", "Order #456 delivered"],
+                        instructions="Extract operational status signals for logistics analytics",
+                )
+        )
+        Model = schema.model  # dynamic Pydantic model
+        task = schema.task    # PreparedTask for batch extraction
+
+The implementation purposefully does *not* emit or depend on JSON Schema; the
+authoritative contract is the recursive ``ObjectSpec`` tree.
+"""
+
+from dataclasses import dataclass
+
+from openai import OpenAI
+from openai.types.responses import ParsedResponse
+from pydantic import BaseModel, Field
+
+from openaivec._model import PreparedTask
+from openaivec._schema.spec import ObjectSpec, _build_model
+
+# Internal module: explicitly not part of public API
+__all__: list[str] = []
+
+
+class SchemaInferenceOutput(BaseModel):
+    """Result of a schema inference round.
+
+    Contains the normalized *instructions*, objective *examples_summary*, the root
+    hierarchical ``object_spec`` contract, and the canonical reusable
+    ``inference_prompt``. The prompt MUST be fully derivable from the other
+    components (no new unstated facts) to preserve traceability.
+
+    Attributes:
+        instructions: Unambiguous restatement of the user's objective.
+        examples_summary: Neutral description of structural / semantic patterns
+            observed in the examples.
+        examples_instructions_alignment: Mapping from instructions facets to concrete
+            recurring evidence (or explicit gaps) anchoring extraction scope.
+        object_spec: Root ``ObjectSpec`` (UpperCamelCase name) whose ``fields``
+            recursively define the extraction schema.
+        inference_prompt: Canonical instructions enforcing exact field names,
+            hierarchy, and types (no additions/removals/renames).
+    """
+
+    instructions: str = Field(
+        description=(
+            "Normalized, unambiguous restatement of the user objective with redundant, vague, or "
+            "conflicting phrasing removed."
+        )
+    )
+    examples_summary: str = Field(
+        description=(
+            "Objective characterization of the provided examples: content domain, structure, recurring "
+            "patterns, and notable constraints."
+        )
+    )
+    examples_instructions_alignment: str = Field(
+        description=(
+            "Explanation of how observable recurring patterns in the examples substantiate and bound the stated "
+            "instructions. Should reference instructions facets and cite supporting example evidence (or note any "
+            "gaps) to reduce hallucinated fields. Internal diagnostic / quality aid; not required for downstream "
+            "extraction."
+        )
+    )
+    object_spec: ObjectSpec = Field(
+        description=(
+            "Root ObjectSpec (recursive). Each contained object's field list is unique-name ordered and derived "
+            "strictly from observable, repeatable signals aligned with the instructions."
+        )
+    )
+    inference_prompt: str = Field(
+        description=(
+            "Canonical, reusable extraction prompt. Must be derivable from instructions + summaries + object_spec. "
+            "Enforces exact hierarchical field set (names, order per object, types) forbidding additions, removals, "
+            "renames, or subjective language. Self-contained (no TODOs, external refs, or placeholders)."
+        )
+    )
+
+    @classmethod
+    def load(cls, path: str) -> "SchemaInferenceOutput":
+        """Load an inferred schema from a JSON file.
+
+        Args:
+            path (str): Path to a UTF‑8 JSON document previously produced via ``save``.
+
+        Returns:
+            InferredSchema: Reconstructed instance.
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            return cls.model_validate_json(f.read())
+
+    @property
+    def model(self) -> type[BaseModel]:
+        """Dynamically materialized Pydantic model for the inferred schema.
+
+        Equivalent to calling :meth:`build_model` each access (not cached).
+
+        Returns:
+            type[BaseModel]: Fresh model type reflecting ``fields`` ordering.
+        """
+        return self.build_model()
+
+    @property
+    def task(self) -> PreparedTask:
+        """PreparedTask integrating the schema's extraction prompt & model.
+
+        Returns:
+            PreparedTask: Ready for batched structured extraction calls.
+        """
+        return PreparedTask(
+            instructions=self.inference_prompt,
+            response_format=self.model,
+        )
+
+    def build_model(self) -> type[BaseModel]:
+        return _build_model(self.object_spec)
+
+    def save(self, path: str) -> None:
+        """Persist this inferred schema as pretty‑printed JSON.
+
+        Args:
+            path (str): Destination filesystem path.
+        """
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(self.model_dump_json(indent=2))
+
+
+class SchemaInferenceInput(BaseModel):
+    """Input payload for schema inference.
+
+    Attributes:
+        examples: Representative sample texts restricted to the in‑scope
+            distribution (exclude outliers / noise). Size should be *minimal*
+            yet sufficient to surface recurring patterns.
+        instructions: Plain language description of downstream usage (analytics,
+            filtering, enrichment, feature engineering, etc.). Guides field
+            relevance & exclusion of outcome labels.
+    """
+
+    examples: list[str] = Field(
+        description=(
+            "Representative sample texts (strings). Provide only data the schema should generalize over; "
+            "exclude outliers not in scope."
+        )
+    )
+    instructions: str = Field(
+        description=(
+            "Plain language statement describing the downstream use of the extracted structured data (e.g. "
+            "analytics, filtering, enrichment)."
+        )
+    )
+
+
+_INFER_INSTRUCTIONS = """
+You are a schema inference engine.
+
+Task:
+1. Normalize the user's instructions (eliminate ambiguity, redundancy, contradictions).
+2. Objectively summarize observable patterns in the example texts.
+3. Produce an "examples_instructions_alignment" explanation mapping instructions facets to concrete recurring
+     evidence (or gaps).
+4. Propose a minimal hierarchical schema (root ObjectSpec) comprised of reliably extractable fields. Use nesting ONLY
+     when a group of fields forms a cohesive sub-entity repeated in the data; otherwise keep flat.
+5. Skip fields likely missing in a large share (>~20%) of realistic inputs.
+6. Provide enum_spec ONLY when a small stable closed categorical set (1–{_MAX_ENUM_VALUES} raw tokens) is clearly
+     evidenced; never invent unseen categories.
+7. If the instructions indicate prediction (predict / probability / likelihood),
+   output only explanatory features (no target restatement).
+
+Rules:
+- Field names: lower snake_case, unique within each object, regex ^[a-z][a-z0-9_]*$, no subjective adjectives.
+- Field types: string | integer | float | boolean | enum | object | string_array | integer_array | float_array |
+    boolean_array | enum_array | object_array
+    * *_array are homogeneous lists of their primitive / enum / object base type.
+    * Use object/object_array ONLY for semantically cohesive grouped attributes; avoid gratuitous layers.
+- Enumerations: use enum_spec { name (UpperCamelCase), values [raw_tokens...] }. values length 1–{_MAX_ENUM_VALUES}.
+    Use ONLY when closed set is evidenced. Otherwise, use string.
+- Numeric (integer|float) names encode explicit unit/measure suffix (e.g. *_count, *_seconds, *_usd, *_ratio, *_score).
+- Boolean names start with 'is_' followed by positive predicate (no negations like is_not_*).
+- Array field names SHOULD end with '_array' for primitive/enum arrays; object_array
+    fields may use plural noun or *_array pattern.
+- Descriptions: concise, objective extraction criteria (no marketing/emotion/speculation).
+- Exclude direct outcome labels in predictive contexts.
+- Avoid superficial renames; semantic transformation only.
+- Keep total field count focused (typically <= 16) optimizing for reusable analytical / ML features.
+
+Output contract:
+Return exactly an InferredSchema JSON object with keys:
+        - instructions (string)
+        - examples_summary (string)
+        - examples_instructions_alignment (string)
+        - object_spec (ObjectSpec: name, fields[list[FieldSpec]])
+        - inference_prompt (string)
+Where each FieldSpec includes: name, type, description, optional enum_spec (for
+enum / enum_array), optional object_spec (for object / object_array).
+""".strip()
+
+
+@dataclass(frozen=True)
+class SchemaInferer:
+    """High-level orchestrator for schema inference against the Responses API.
+
+    Responsibilities:
+        * Issue a structured parsing request with strict instructions.
+        * Retry (up to ``max_retries``) when the produced field list violates
+          baseline structural rules (duplicate names, unsupported types, etc.).
+        * Return a fully validated ``InferredSchema`` ready for dynamic model
+          generation & downstream batch extraction.
+
+    The inferred schema intentionally avoids JSON Schema intermediates; the
+    authoritative contract is the ordered ``FieldSpec`` list.
+
+    Attributes:
+        client: OpenAI client for calling ``responses.parse``.
+        model_name: Model / deployment identifier.
+    """
+
+    client: OpenAI
+    model_name: str
+
+    def infer_schema(self, data: SchemaInferenceInput, *args, max_retries: int = 8, **kwargs) -> SchemaInferenceOutput:
+        """Infer a validated schema from representative examples.
+
+          Workflow:
+                1. Submit ``SchemaInferenceInput`` (JSON) + instructions via
+                    ``responses.parse`` requesting an ``InferredSchema`` object.
+                2. Attempt dynamic model build (``parsed.build_model()``) which performs recursive
+                    structural validation (names, types, enum/object specs) via the dynamic layer.
+                3. Retry (up to ``max_retries``) on validation failure.
+
+        Args:
+            data (SchemaInferenceInput): Representative examples + instructions.
+            *args: Positional passthrough to ``client.responses.parse``.
+            max_retries (int, optional): Attempts before surfacing the last validation error
+                (must be >= 1). Defaults to 3.
+            **kwargs: Keyword passthrough to ``client.responses.parse``.
+
+        Returns:
+            InferredSchema: Fully validated schema (instructions, examples summary,
+            ordered fields, extraction prompt).
+
+        Raises:
+            ValueError: Validation still fails after exhausting retries.
+        """
+        if max_retries < 1:
+            raise ValueError("max_retries must be >= 1")
+
+        last_err: Exception | None = None
+        previous_errors: list[str] = []
+        for attempt in range(max_retries):
+            if attempt == 0:
+                instructions = _INFER_INSTRUCTIONS
+            else:
+                # Provide structured feedback for correction. Keep concise and prohibit speculative expansion.
+                feedback_lines = [
+                    "--- PRIOR VALIDATION FEEDBACK ---",
+                ]
+                for i, err in enumerate(previous_errors[-5:], 1):  # include last up to 5 errors
+                    feedback_lines.append(f"{i}. {err}")
+                feedback_lines.extend(
+                    [
+                        "Adjust ONLY listed issues; avoid adding brand-new fields unless essential.",
+                        "Don't hallucinate or broaden enum_values unless enum rule caused failure.",
+                        "Duplicate names: minimally rename; keep semantics.",
+                        "Unsupported type: change to string|integer|float|boolean (no new facts).",
+                        "Bad enum length: drop enum or constrain to 2–24 evidenced tokens.",
+                    ]
+                )
+                instructions = _INFER_INSTRUCTIONS + "\n\n" + "\n".join(feedback_lines)
+
+            response: ParsedResponse[SchemaInferenceOutput] = self.client.responses.parse(
+                model=self.model_name,
+                instructions=instructions,
+                input=data.model_dump_json(),
+                text_format=SchemaInferenceOutput,
+                *args,
+                **kwargs,
+            )
+            parsed = response.output_parsed
+            try:
+                # Validate the field list structure
+                parsed.build_model()
+                return parsed
+            except ValueError as e:
+                last_err = e
+                previous_errors.append(str(e))
+                if attempt == max_retries - 1:
+                    raise ValueError(
+                        f"Schema validation failed after {max_retries} attempts. Last error: {last_err}"
+                    ) from last_err
+
+        if last_err:
+            raise last_err
+        raise RuntimeError("unreachable retry loop state")

openaivec/_schema/spec.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field, create_model
+
+__all__: list[str] = []
+
+_MAX_ENUM_VALUES = 24
+
+
+class FieldSpec(BaseModel):
+    name: str = Field(
+        description=(
+            "Field name in lower_snake_case. Rules: (1) Use only lowercase letters, numbers, and underscores; "
+            "must start with a letter. (2) For numeric quantities append an explicit unit (e.g. 'duration_seconds', "
+            "'price_usd'). (3) Boolean fields use an affirmative 'is_' prefix (e.g. 'is_active'); avoid negative / "
+            "ambiguous forms like 'is_deleted' (prefer 'is_active', 'is_enabled'). (4) Name must be unique within the "
+            "containing object."
+        )
+    )
+    type: Literal[
+        "string",
+        "integer",
+        "float",
+        "boolean",
+        "enum",
+        "object",
+        "string_array",
+        "integer_array",
+        "float_array",
+        "boolean_array",
+        "enum_array",
+        "object_array",
+    ] = Field(
+        description=(
+            "Logical data type. Allowed values: string | integer | float | boolean | enum | object | string_array | "
+            "integer_array | float_array | boolean_array | enum_array | object_array. *_array variants represent a "
+            "homogeneous list of the base type. 'enum' / 'enum_array' require 'enum_spec'. 'object' / 'object_array' "
+            "require 'object_spec'. Primitives must not define 'enum_spec' or 'object_spec'."
+        )
+    )
+    description: str = Field(
+        description=(
+            "Human‑readable, concise explanation of the field's meaning and business intent. Should clarify units, "
+            "value semantics, and any domain constraints not captured by type. 1–2 sentences; no implementation notes."
+        )
+    )
+    enum_spec: EnumSpec | None = Field(
+        default=None,
+        description=(
+            "Enumeration specification for 'enum' / 'enum_array'. Must be provided (non-empty) for those types and "
+            "omitted for all others. Maximum size enforced by constant."
+        ),
+    )
+    object_spec: ObjectSpec | None = Field(
+        default=None,
+        description=(
+            "Nested object schema. Required for 'object' / 'object_array'; must be omitted for every other type. The "
+            "contained 'name' is used to derive the generated nested Pydantic model class name."
+        ),
+    )
+
+
+class EnumSpec(BaseModel):
+    """Enumeration specification for enum / enum_array field types.
+
+    Attributes:
+        name: Required Enum class name (UpperCamelCase). Must match ^[A-Z][A-Za-z0-9]*$. Previously optional; now
+            explicit to remove implicit coupling to the field name and make schemas self‑describing.
+        values: Raw label values (1–_MAX_ENUM_VALUES before de‑dup). Values are uppercased then
+            de-duplicated using a set; ordering of generated Enum members is not guaranteed. Any
+            casing variants collapse silently to a single member.
+    """
+
+    name: str = Field(
+        description=("Required Enum class name (UpperCamelCase). Valid pattern: ^[A-Z][A-Za-z0-9]*$."),
+    )
+    values: list[str] = Field(
+        description=(
+            f"Raw enum label values (1–{_MAX_ENUM_VALUES}). Uppercased then deduplicated; order of members "
+            "not guaranteed."
+        )
+    )
+
+
+class ObjectSpec(BaseModel):
+    name: str = Field(
+        description=(
+            "Object model class name in UpperCamelCase (singular noun). Must match ^[A-Z][A-Za-z0-9]*$ and is used "
+            "directly as the generated Pydantic model class name (no transformation)."
+        )
+    )
+    fields: list[FieldSpec] = Field(
+        description=(
+            "Non-empty list of FieldSpec definitions composing the object. Each field name must be unique; order is "
+            "preserved in the generated model."
+        )
+    )
+
+
+def _build_model(object_spec: ObjectSpec) -> type[BaseModel]:
+    lower_sname_pattern = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$")
+    upper_camel_pattern = re.compile(r"^[A-Z][A-Za-z0-9]*$")
+    type_map: dict[str, type] = {
+        "string": str,
+        "integer": int,
+        "float": float,
+        "boolean": bool,
+        "string_array": list[str],
+        "integer_array": list[int],
+        "float_array": list[float],
+        "boolean_array": list[bool],
+    }
+    output_fields: dict[str, tuple[type, object]] = {}
+
+    field_names: list[str] = [field.name for field in object_spec.fields]
+
+    # Assert that names of fields are not duplicated
+    if len(field_names) != len(set(field_names)):
+        raise ValueError("Field names must be unique within the object spec.")
+
+    for field in object_spec.fields:
+        # Assert that field names are lower_snake_case
+        if not lower_sname_pattern.match(field.name):
+            raise ValueError(f"Field name '{field.name}' must be in lower_snake_case format (e.g., 'my_field_name').")
+
+        # (EnumSpec.name now mandatory; no need to derive a fallback name from the field.)
+        match field:
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                description=description,
+                enum_spec=None,
+                object_spec=None,
+            ):
+                field_type = type_map[field.type]
+                output_fields[name] = (field_type, Field(description=description))
+
+            case FieldSpec(name=name, type="enum", description=description, enum_spec=enum_spec, object_spec=None) if (
+                enum_spec
+                and 0 < len(enum_spec.values) <= _MAX_ENUM_VALUES
+                and upper_camel_pattern.match(enum_spec.name)
+            ):
+                member_names = list({v.upper() for v in enum_spec.values})
+                enum_type = Enum(enum_spec.name, member_names)
+                output_fields[name] = (enum_type, Field(description=description))
+
+            case FieldSpec(
+                name=name, type="enum_array", description=description, enum_spec=enum_spec, object_spec=None
+            ) if (
+                enum_spec
+                and 0 < len(enum_spec.values) <= _MAX_ENUM_VALUES
+                and upper_camel_pattern.match(enum_spec.name)
+            ):
+                member_names = list({v.upper() for v in enum_spec.values})
+                enum_type = Enum(enum_spec.name, member_names)
+                output_fields[name] = (list[enum_type], Field(description=description))
+
+            case FieldSpec(
+                name=name, type="object", description=description, enum_spec=None, object_spec=object_spec
+            ) if object_spec and upper_camel_pattern.match(object_spec.name):
+                nested_model = _build_model(object_spec)
+                output_fields[name] = (nested_model, Field(description=description))
+
+            case FieldSpec(
+                name=name, type="object_array", description=description, enum_spec=None, object_spec=object_spec
+            ) if object_spec and upper_camel_pattern.match(object_spec.name):
+                nested_model = _build_model(object_spec)
+                output_fields[name] = (list[nested_model], Field(description=description))
+
+            # ---- Error cases (explicit reasons) ----
+            # Enum type without enum_spec (None or empty)
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if not enum_spec or not enum_spec.values:
+                raise ValueError(f"Field '{name}': enum type requires non-empty enum_spec values list.")
+            # Enum type exceeding max length
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and len(enum_spec.values) > _MAX_ENUM_VALUES:
+                raise ValueError(
+                    (
+                        f"Field '{name}': enum type supports at most {_MAX_ENUM_VALUES} enum_spec values "
+                        f"(got {len(enum_spec.values)})."
+                    )
+                )
+            # Enum type invalid explicit name pattern
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and not upper_camel_pattern.match(enum_spec.name):
+                raise ValueError(
+                    (f"Field '{name}': enum_spec.name '{enum_spec.name}' invalid – must match ^[A-Z][A-Za-z0-9]*$")
+                )
+            # Enum type incorrectly provides an object_spec
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': enum type must not provide object_spec (got object_spec={object_spec!r})."
+                )
+            # Enum array type without enum_spec
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if not enum_spec or not enum_spec.values:
+                raise ValueError(f"Field '{name}': enum_array type requires non-empty enum_spec values list.")
+            # Enum array type exceeding max length
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and len(enum_spec.values) > _MAX_ENUM_VALUES:
+                raise ValueError(
+                    (
+                        f"Field '{name}': enum_array type supports at most {_MAX_ENUM_VALUES} enum_spec values "
+                        f"(got {len(enum_spec.values)})."
+                    )
+                )
+            # Enum array type invalid explicit name pattern
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and not upper_camel_pattern.match(enum_spec.name):
+                raise ValueError(
+                    (f"Field '{name}': enum_spec.name '{enum_spec.name}' invalid – must match ^[A-Z][A-Za-z0-9]*$")
+                )
+            # Enum array type incorrectly provides an object_spec
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': enum_array type must not provide object_spec (got object_spec={object_spec!r})."
+                )
+            # Object type missing object_spec
+            case FieldSpec(
+                name=name,
+                type="object",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ):
+                raise ValueError(f"Field '{name}': object type requires object_spec (got object_spec=None).")
+            # Object array type missing object_spec
+            case FieldSpec(
+                name=name,
+                type="object_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ):
+                raise ValueError(f"Field '{name}': object_array type requires object_spec (got object_spec=None).")
+            # Object/object_array provided but invalid name pattern
+            case FieldSpec(
+                name=name,
+                type="object" | "object_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None and not upper_camel_pattern.match(object_spec.name):
+                raise ValueError(
+                    (
+                        f"Field '{name}': object_spec.name '{object_spec.name}' must be UpperCamelCase "
+                        "(regex ^[A-Z][A-Za-z0-9]*$) and contain only letters and digits."
+                    )
+                )
+            # Object/object_array types must not provide enum_spec
+            case FieldSpec(
+                name=name,
+                type="object" | "object_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if enum_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': {field.type} must not define enum_spec (got enum_spec={enum_spec!r})."
+                )
+            # Primitive / simple array types must not have enum_spec
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if enum_spec is not None:
+                raise ValueError(
+                    (f"Field '{name}': type '{field.type}' must not define enum_spec (got enum_spec={enum_spec!r}).")
+                )
+            # Primitive / simple array types must not have object_spec
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                enum_spec=None,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    (
+                        f"Field '{name}': type '{field.type}' must not define object_spec "
+                        f"(got object_spec={object_spec!r})."
+                    )
+                )
+            # Any other unmatched combination
+            case FieldSpec() as f:
+                raise ValueError(
+                    (
+                        "Field configuration invalid / unrecognized combination: "
+                        f"name={f.name!r}, type={f.type!r}, enum_spec={'set' if f.enum_spec else None}, "
+                        f"object_spec={'set' if f.object_spec else None}."
+                    )
+                )
+
+    return create_model(object_spec.name, **output_fields)