structx 0.6.0__tar.gz → 0.6.2__tar.gz

{structx-0.6.0/structx.egg-info → structx-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.0
+Version: 0.6.2
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -64,9 +64,12 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.0-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.2-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
+See the [project roadmap](docs/ROADMAP.md) for planned portable business rules
+and semantic validation work.
+
 `structx` is a powerful Python library for extracting structured data from text,
 tables, and documents using Large Language Models (LLMs). It passes existing
 PDFs directly to vision-capable models; the optional `docs` extra converts other

{structx-0.6.0 → structx-0.6.2}/README.md

@@ -4,9 +4,12 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.0-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.2-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
+See the [project roadmap](docs/ROADMAP.md) for planned portable business rules
+and semantic validation work.
+
 `structx` is a powerful Python library for extracting structured data from text,
 tables, and documents using Large Language Models (LLMs). It passes existing
 PDFs directly to vision-capable models; the optional `docs` extra converts other

{structx-0.6.0 → structx-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structx"
-version = "0.6.0"
+version = "0.6.2"
 description = "Structured data extraction from text using LLMs and dynamic model generation"
 authors = [{ name = "blacksuan19", email = "py@aolabs.dev" }]
 license-files = ["LICENSE"]
@@ -92,9 +92,9 @@ torchvision = [
 ]
 
 [tool.bumpver]
-current_version = "0.6.0"
+current_version = "0.6.2"
 version_pattern = "MAJOR.MINOR.PATCH"
-commit_message = "Bump version {old_version} -> {new_version}"
+commit_message = "chore(release): bump version {old_version} -> {new_version}"
 commit = true
 tag = true
 push = true

{structx-0.6.0 → structx-0.6.2}/structx/__init__.py

@@ -11,8 +11,17 @@ from structx.core.models import (
     RowResult,
 )
 from structx.extraction.extractor import Extractor
+from structx.schema import (
+    ContainerTypeCapability,
+    ScalarTypeCapability,
+    TypeCapabilities,
+    TypeModifierCapabilities,
+    get_type_capabilities,
+    model_from_extraction_request,
+    model_to_extraction_request,
+)
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 __all__ = [
     "Extractor",
     "ExtractionConfig",
@@ -22,4 +31,11 @@ __all__ = [
     "ExtractionRequest",
     "ExtractionResult",
     "RowResult",
+    "ScalarTypeCapability",
+    "ContainerTypeCapability",
+    "TypeModifierCapabilities",
+    "TypeCapabilities",
+    "get_type_capabilities",
+    "model_to_extraction_request",
+    "model_from_extraction_request",
 ]

{structx-0.6.0 → structx-0.6.2}/structx/core/models.py

@@ -35,6 +35,13 @@ class ModelField(BaseModel):
     nullable: bool = Field(
         default=True, description="Whether the generated field may be null"
     )
+    has_default: bool = Field(
+        default=False, description="Whether the generated field has an explicit default"
+    )
+    default: Any = Field(
+        default=None,
+        description="JSON-serializable default value when has_default is true",
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -54,8 +61,12 @@ class ModelField(BaseModel):
 
     @model_validator(mode="after")
     def validate_presence_semantics(self) -> "ModelField":
-        if not self.required and not self.nullable:
-            raise ValueError("A non-required field must be nullable")
+        if self.required and self.has_default:
+            raise ValueError("A required field cannot also have a default")
+        if not self.required and not self.nullable and not self.has_default:
+            raise ValueError(
+                "A non-required field must be nullable unless it has an explicit default"
+            )
         return self
 
 

{structx-0.6.0 → structx-0.6.2}/structx/core/type_system.py

@@ -4,7 +4,18 @@ import ast
 import re
 from datetime import date, datetime, time
 from decimal import Decimal
-from typing import Any, Dict, FrozenSet, List, Mapping, Optional, Set, Tuple, Type
+from typing import (
+    Any,
+    Dict,
+    FrozenSet,
+    List,
+    Mapping,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    get_origin,
+)
 from uuid import UUID
 
 
@@ -49,7 +60,7 @@ _ALIASES = {
     "uuid": "UUID",
 }
 
-_PRIMITIVES = {
+CANONICAL_SCALAR_TYPES = (
     "Any",
     "bool",
     "date",
@@ -60,7 +71,33 @@ _PRIMITIVES = {
     "str",
     "time",
     "UUID",
-}
+)
+
+CANONICAL_CONTAINER_TYPES = ("List", "Set", "Dict", "FrozenSet", "Tuple")
+
+SUPPORTED_FIELD_CONSTRAINTS = frozenset(
+    {
+        "alias",
+        "deprecated",
+        "examples",
+        "exclude",
+        "frozen",
+        "ge",
+        "gt",
+        "json_schema_extra",
+        "le",
+        "lt",
+        "max_length",
+        "min_length",
+        "multiple_of",
+        "pattern",
+        "repr",
+        "strict",
+        "title",
+    }
+)
+
+_PRIMITIVES = set(CANONICAL_SCALAR_TYPES)
 
 _RUNTIME_TYPES: Dict[str, Type[Any]] = {
     "Any": Any,
@@ -75,24 +112,16 @@ _RUNTIME_TYPES: Dict[str, Type[Any]] = {
     "UUID": UUID,
 }
 
-_FIELD_CONSTRAINTS = {
-    "alias",
-    "deprecated",
-    "examples",
-    "exclude",
-    "frozen",
-    "ge",
-    "gt",
-    "json_schema_extra",
-    "le",
-    "lt",
-    "max_length",
-    "min_length",
-    "multiple_of",
-    "pattern",
-    "repr",
-    "strict",
-    "title",
+_RUNTIME_TYPE_NAMES = {
+    runtime_type: name for name, runtime_type in _RUNTIME_TYPES.items()
+}
+
+_CONTAINER_ORIGIN_NAMES = {
+    list: "List",
+    set: "Set",
+    dict: "Dict",
+    frozenset: "FrozenSet",
+    tuple: "Tuple",
 }
 
 _LEGACY_TYPES = {
@@ -218,7 +247,7 @@ def _normalize_validation(
     normalized: Dict[str, Any] = {}
 
     for key, value in raw_validation.items():
-        if key in _FIELD_CONSTRAINTS:
+        if key in SUPPORTED_FIELD_CONSTRAINTS:
             normalized[key] = value
 
     for source_key, target_key in _VALIDATION_ALIASES.items():
@@ -250,6 +279,16 @@ def normalize_field_definition(
     return normalize_type_expression(legacy_type), normalized_validation
 
 
+def canonical_scalar_name(annotation: Any) -> Optional[str]:
+    """Return the canonical name for a supported runtime scalar type."""
+    return _RUNTIME_TYPE_NAMES.get(annotation)
+
+
+def canonical_container_name(annotation: Any) -> Optional[str]:
+    """Return the canonical name for a supported container annotation."""
+    return _CONTAINER_ORIGIN_NAMES.get(get_origin(annotation) or annotation)
+
+
 def normalize_type_expression(value: str) -> str:
     """Normalize common JSON, TypeScript, and Python type syntax."""
     if not isinstance(value, str) or not value.strip():

{structx-0.6.0 → structx-0.6.2}/structx/extraction/generator.py

@@ -38,6 +38,14 @@ class ModelGenerator:
             return Optional[field_type]
         return field_type
 
+    @staticmethod
+    def _field_default(field: ModelField):
+        if field.required:
+            return ...
+        if field.has_default:
+            return field.default
+        return None
+
     @classmethod
     def _create_nested_model(
         cls,
@@ -72,7 +80,7 @@ class ModelGenerator:
             field_definitions[field.name] = (
                 cls._field_annotation(field, field_type),
                 Field(
-                    default=... if field.required else None,
+                    default=cls._field_default(field),
                     description=field.description,
                     **(field.validation or {}),
                 ),
@@ -81,11 +89,7 @@ class ModelGenerator:
         model_name = f"{parent_name}{field_name}" if parent_name else field_name
 
         # Create the model using Pydantic v2 style
-        model_options = (
-            {"__config__": ConfigDict(frozen=True)}
-            if frozen
-            else {"__base__": BaseModel}
-        )
+        model_options = {"__config__": ConfigDict(frozen=frozen, validate_default=True)}
         model = create_model(model_name, **model_options, **field_definitions)
 
         # Add description as model docstring
@@ -117,6 +121,7 @@ class ModelGenerator:
             field_description=request.model_description,
             nested_fields=request.fields,
         )
+        setattr(model, "__structx_definition__", request.model_copy(deep=True))
 
         logger.debug("Model generation completed")
 

structx-0.6.2/structx/schema.py

@@ -0,0 +1,368 @@
+"""Portable schema definitions and UI-facing type capabilities."""
+
+from __future__ import annotations
+
+from types import UnionType
+from typing import (
+    Annotated,
+    Any,
+    Dict,
+    List,
+    Mapping,
+    Optional,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_core import PydanticUndefined, to_jsonable_python
+
+from structx.core.exceptions import ModelGenerationError
+from structx.core.models import ExtractionRequest, ModelField
+from structx.core.type_system import (
+    CANONICAL_CONTAINER_TYPES,
+    CANONICAL_SCALAR_TYPES,
+    SUPPORTED_FIELD_CONSTRAINTS,
+    canonical_container_name,
+    canonical_scalar_name,
+)
+from structx.extraction.generator import ModelGenerator
+
+
+class ScalarTypeCapability(BaseModel):
+    """One canonical scalar type available to schema builders."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    label: str
+    constraints: List[str] = Field(default_factory=list)
+    advanced: bool = False
+
+
+class ContainerTypeCapability(BaseModel):
+    """One canonical container and the item shapes supported by StructX."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    label: str
+    description: str
+    allowed_item_kinds: List[str]
+    ordered: bool
+    unique: bool
+    advanced: bool = False
+
+
+class TypeModifierCapabilities(BaseModel):
+    """Presence and nullability controls kept separate from value types."""
+
+    model_config = ConfigDict(frozen=True)
+
+    required: bool = True
+    nullable: bool = True
+    default: bool = True
+
+
+class TypeCapabilities(BaseModel):
+    """Versioned canonical type catalog for external schema builders."""
+
+    model_config = ConfigDict(frozen=True)
+
+    schema_version: str = "1"
+    scalars: List[ScalarTypeCapability]
+    containers: List[ContainerTypeCapability]
+    modifiers: TypeModifierCapabilities = Field(
+        default_factory=TypeModifierCapabilities
+    )
+
+
+_STRING_CONSTRAINTS = ["min_length", "max_length", "pattern", "strict"]
+_NUMBER_CONSTRAINTS = ["gt", "ge", "lt", "le", "multiple_of", "strict"]
+_SCALAR_METADATA = {
+    "str": ("Text", _STRING_CONSTRAINTS, False),
+    "int": ("Integer", _NUMBER_CONSTRAINTS, False),
+    "float": ("Number", _NUMBER_CONSTRAINTS, False),
+    "Decimal": ("Decimal", _NUMBER_CONSTRAINTS, False),
+    "bool": ("Boolean", ["strict"], False),
+    "date": ("Date", ["strict"], False),
+    "datetime": ("Date and time", ["strict"], False),
+    "time": ("Time", ["strict"], False),
+    "UUID": ("UUID", ["strict"], False),
+    "Any": ("Any value", [], True),
+}
+
+_CONTAINER_METADATA = {
+    "List": {
+        "label": "List",
+        "description": "Ordered values that may contain duplicates",
+        "allowed_item_kinds": ["scalar", "object", "container"],
+        "ordered": True,
+        "unique": False,
+    },
+    "Set": {
+        "label": "Set",
+        "description": "Unique values without a stable order",
+        "allowed_item_kinds": ["hashable_scalar", "object"],
+        "ordered": False,
+        "unique": True,
+    },
+    "Dict": {
+        "label": "Map",
+        "description": "Text keys mapped to values",
+        "allowed_item_kinds": ["scalar", "container"],
+        "ordered": False,
+        "unique": True,
+        "advanced": True,
+    },
+    "FrozenSet": {
+        "label": "Frozen set",
+        "description": "Immutable unique values without a stable order",
+        "allowed_item_kinds": ["hashable_scalar", "object"],
+        "ordered": False,
+        "unique": True,
+        "advanced": True,
+    },
+    "Tuple": {
+        "label": "Tuple",
+        "description": "Fixed-position values",
+        "allowed_item_kinds": ["scalar", "object"],
+        "ordered": True,
+        "unique": False,
+        "advanced": True,
+    },
+}
+
+_TYPE_CAPABILITIES = TypeCapabilities(
+    scalars=[
+        ScalarTypeCapability(
+            id=type_id,
+            label=_SCALAR_METADATA[type_id][0],
+            constraints=_SCALAR_METADATA[type_id][1],
+            advanced=_SCALAR_METADATA[type_id][2],
+        )
+        for type_id in CANONICAL_SCALAR_TYPES
+    ],
+    containers=[
+        ContainerTypeCapability(id=type_id, **_CONTAINER_METADATA[type_id])
+        for type_id in CANONICAL_CONTAINER_TYPES
+    ],
+)
+
+
+def get_type_capabilities() -> TypeCapabilities:
+    """Return the canonical, alias-free type catalog for schema-builder UIs."""
+    return _TYPE_CAPABILITIES.model_copy(deep=True)
+
+
+def _unsupported(message: str) -> ModelGenerationError:
+    return ModelGenerationError(message)
+
+
+def _model_has_custom_behavior(model: Type[BaseModel]) -> bool:
+    decorators = getattr(model, "__pydantic_decorators__", None)
+    if decorators is not None:
+        collections = (
+            "validators",
+            "field_validators",
+            "root_validators",
+            "field_serializers",
+            "model_serializers",
+            "model_validators",
+            "computed_fields",
+        )
+        if any(getattr(decorators, name, {}) for name in collections):
+            return True
+    return bool(getattr(model, "model_computed_fields", {}))
+
+
+def _unwrap_annotated(annotation: Any) -> Any:
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+    return annotation
+
+
+def _unwrap_nullable(annotation: Any) -> tuple[Any, bool]:
+    annotation = _unwrap_annotated(annotation)
+    origin = get_origin(annotation)
+    if origin not in {Union, UnionType}:
+        return annotation, False
+
+    arguments = get_args(annotation)
+    non_null = [argument for argument in arguments if argument is not type(None)]
+    if len(non_null) != len(arguments) - 1 or len(non_null) != 1:
+        raise _unsupported(
+            f"Only a single type combined with None is supported, received {annotation!r}"
+        )
+    return _unwrap_annotated(non_null[0]), True
+
+
+def _model_fields(
+    model: Type[BaseModel], seen: set[Type[BaseModel]]
+) -> List[ModelField]:
+    if model in seen:
+        raise _unsupported(
+            f"Recursive model definitions are not supported: {model.__name__}"
+        )
+    if _model_has_custom_behavior(model):
+        raise _unsupported(
+            f"Custom validators, serializers, and computed fields cannot be serialized: {model.__name__}"
+        )
+
+    seen.add(model)
+    try:
+        return [
+            _field_from_pydantic(name, field, seen)
+            for name, field in model.model_fields.items()
+        ]
+    finally:
+        seen.remove(model)
+
+
+def _annotation_definition(
+    annotation: Any, seen: set[Type[BaseModel]]
+) -> tuple[str, Optional[List[ModelField]], bool]:
+    annotation, nullable = _unwrap_nullable(annotation)
+    scalar = canonical_scalar_name(annotation)
+    if scalar is not None:
+        return scalar, None, nullable
+
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return "Dict[str, Any]", _model_fields(annotation, seen), nullable
+
+    container = canonical_container_name(annotation)
+    if container is None:
+        raise _unsupported(f"Unsupported Pydantic field type: {annotation!r}")
+
+    arguments = get_args(annotation)
+    if container in {"List", "Set", "FrozenSet"}:
+        if len(arguments) != 1:
+            raise _unsupported(f"{container} requires one item type")
+        item_type, nested_fields, item_nullable = _annotation_definition(
+            arguments[0], seen
+        )
+        if item_nullable:
+            item_type = f"Optional[{item_type}]"
+        expression = f"{container}[{item_type}]"
+    elif container == "Dict":
+        if len(arguments) != 2:
+            raise _unsupported("Dict requires key and value types")
+        key_type, key_nested, key_nullable = _annotation_definition(arguments[0], seen)
+        value_type, value_nested, value_nullable = _annotation_definition(
+            arguments[1], seen
+        )
+        if key_nested or value_nested or key_nullable:
+            raise _unsupported(
+                "Nested models and nullable keys inside Dict are not supported"
+            )
+        if value_nullable:
+            value_type = f"Optional[{value_type}]"
+        expression = f"Dict[{key_type}, {value_type}]"
+        nested_fields = None
+    else:
+        if not arguments or Ellipsis in arguments:
+            raise _unsupported("Tuple requires explicit fixed-position item types")
+        item_definitions = [
+            _annotation_definition(argument, seen) for argument in arguments
+        ]
+        nested = [definition for definition in item_definitions if definition[1]]
+        if len(nested) > 1 or (nested and len(arguments) > 1):
+            raise _unsupported(
+                "Tuple cannot contain a nested model alongside other item types"
+            )
+        item_types = [
+            f"Optional[{item_type}]" if item_nullable else item_type
+            for item_type, _, item_nullable in item_definitions
+        ]
+        expression = f"Tuple[{', '.join(item_types)}]"
+        nested_fields = nested[0][1] if nested else None
+
+    if nullable:
+        expression = f"Optional[{expression}]"
+    return expression, nested_fields, nullable
+
+
+def _field_validation(field: Any) -> Dict[str, Any]:
+    validation: Dict[str, Any] = {}
+    for key in SUPPORTED_FIELD_CONSTRAINTS:
+        value = getattr(field, key, None)
+        if key == "repr" and value is True:
+            continue
+        if value is not None and not callable(value):
+            validation[key] = to_jsonable_python(value)
+
+    for metadata in field.metadata:
+        for key in SUPPORTED_FIELD_CONSTRAINTS:
+            value = getattr(metadata, key, None)
+            if value is not None and not callable(value):
+                validation[key] = to_jsonable_python(value)
+    return validation
+
+
+def _field_from_pydantic(
+    name: str, field: Any, seen: set[Type[BaseModel]]
+) -> ModelField:
+    if field.default_factory is not None:
+        raise _unsupported(f"Default factories cannot be serialized for field {name!r}")
+
+    field_type, nested_fields, nullable = _annotation_definition(field.annotation, seen)
+    required = field.is_required()
+    has_default = not required and field.default is not PydanticUndefined
+    default = to_jsonable_python(field.default) if has_default else None
+    if has_default and default is None:
+        nullable = True
+
+    return ModelField(
+        name=name,
+        type=field_type,
+        description=field.description or "",
+        validation=_field_validation(field),
+        nested_fields=nested_fields,
+        required=required,
+        nullable=nullable,
+        has_default=has_default,
+        default=default,
+    )
+
+
+def model_to_extraction_request(
+    model: Type[BaseModel],
+    *,
+    model_name: Optional[str] = None,
+    model_description: Optional[str] = None,
+) -> ExtractionRequest:
+    """Convert a declarative Pydantic model into a portable definition."""
+    if not isinstance(model, type) or not issubclass(model, BaseModel):
+        raise TypeError("model must be a Pydantic BaseModel class")
+
+    stored_definition = getattr(model, "__structx_definition__", None)
+    if isinstance(stored_definition, ExtractionRequest):
+        updates = {}
+        if model_name is not None:
+            updates["model_name"] = model_name
+        if model_description is not None:
+            updates["model_description"] = model_description
+        return stored_definition.model_copy(deep=True, update=updates)
+
+    description = model_description
+    if description is None:
+        description = (model.__dict__.get("__doc__") or "").strip()
+    return ExtractionRequest(
+        model_name=model_name or model.__name__,
+        model_description=description,
+        fields=_model_fields(model, set()),
+    )
+
+
+def model_from_extraction_request(
+    request: ExtractionRequest | Mapping[str, Any],
+) -> Type[BaseModel]:
+    """Create a runtime Pydantic model from a portable definition or JSON data."""
+    definition = (
+        request
+        if isinstance(request, ExtractionRequest)
+        else ExtractionRequest.model_validate(request)
+    )
+    return ModelGenerator.from_extraction_request(definition)

{structx-0.6.0 → structx-0.6.2}/structx/utils/prompts.py

@@ -6,7 +6,8 @@ Use only these field type forms: str, int, float, bool, date, datetime, time,
 Decimal, UUID, Any, List[T], Dict[str, T], Set[T], and Optional[T].
 Fields are optional and nullable by default. Set required=true for core values
 explicitly requested by the user. Set nullable=false only together with
-required=true when null is invalid.
+required=true or has_default=true when null is invalid. Use has_default and
+default only when the user explicitly requests a default value.
 Do not add Optional unless it clarifies intent.
 Represent nested objects with nested_fields and use List[Any] or Dict[str, Any]
 only when a more precise type cannot be determined."""

{structx-0.6.0 → structx-0.6.2/structx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structx
-Version: 0.6.0
+Version: 0.6.2
 Summary: Structured data extraction from text using LLMs and dynamic model generation
 Author-email: blacksuan19 <py@aolabs.dev>
 Classifier: Development Status :: 5 - Production/Stable
@@ -64,9 +64,12 @@ Advanced structured data extraction from any document using LLMs with multimodal
 support.
 
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg?style=for-the-badge)](https://structx.aolabs.dev "Documentation")
-[![PyPI](https://img.shields.io/badge/PyPi-0.6.0-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
+[![PyPI](https://img.shields.io/badge/PyPi-0.6.2-blue?style=for-the-badge)](https://pypi.org/project/structx "Package")
 [![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)](# "Build with GitHub Actions")
 
+See the [project roadmap](docs/ROADMAP.md) for planned portable business rules
+and semantic validation work.
+
 `structx` is a powerful Python library for extracting structured data from text,
 tables, and documents using Large Language Models (LLMs). It passes existing
 PDFs directly to vision-capable models; the optional `docs` extra converts other

{structx-0.6.0 → structx-0.6.2}/structx.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 structx/__init__.py
+structx/schema.py
 structx.egg-info/PKG-INFO
 structx.egg-info/SOURCES.txt
 structx.egg-info/dependency_links.txt
@@ -43,5 +44,6 @@ tests/test_input_and_batch_processors.py
 tests/test_live_llm.py
 tests/test_llm_configuration.py
 tests/test_result_manager_and_helpers.py
+tests/test_schema_contract.py
 tests/test_type_system_and_planning.py
 tests/test_usage.py

structx-0.6.2/tests/test_schema_contract.py

@@ -0,0 +1,169 @@
+import json
+from datetime import date
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+import pytest
+from pydantic import BaseModel, Field, field_validator
+
+from structx import (
+    ExtractionRequest,
+    ModelField,
+    get_type_capabilities,
+    model_from_extraction_request,
+    model_to_extraction_request,
+)
+from structx.core.exceptions import ModelGenerationError
+
+
+class Address(BaseModel):
+    street: str = Field(min_length=2)
+    postal_code: Optional[str] = None
+
+
+class ManualRecord(BaseModel):
+    record_id: UUID
+    amount: Decimal = Decimal("1.50")
+    issued_on: date
+    tags: list[str]
+    unique_codes: set[int]
+    address: Address
+
+
+def field_by_name(request: ExtractionRequest, name: str) -> ModelField:
+    return next(field for field in request.fields if field.name == name)
+
+
+def test_type_capabilities_are_canonical_and_alias_free():
+    capabilities = get_type_capabilities()
+
+    scalar_ids = {item.id for item in capabilities.scalars}
+    container_ids = {item.id for item in capabilities.containers}
+
+    assert scalar_ids == {
+        "Any",
+        "bool",
+        "date",
+        "datetime",
+        "Decimal",
+        "float",
+        "int",
+        "str",
+        "time",
+        "UUID",
+    }
+    assert container_ids == {"Dict", "FrozenSet", "List", "Set", "Tuple"}
+    assert "string" not in scalar_ids
+    assert "array" not in container_ids
+    assert capabilities.modifiers.required is True
+    assert capabilities.modifiers.nullable is True
+
+
+def test_manual_pydantic_model_round_trips_through_extraction_request():
+    request = model_to_extraction_request(
+        ManualRecord,
+        model_description="A manually defined record",
+    )
+
+    assert request.model_name == "ManualRecord"
+    assert request.model_description == "A manually defined record"
+
+    amount = field_by_name(request, "amount")
+    assert amount.type == "Decimal"
+    assert amount.required is False
+    assert amount.nullable is False
+    assert amount.has_default is True
+    assert amount.default == "1.50"
+
+    assert field_by_name(request, "tags").type == "List[str]"
+    assert field_by_name(request, "unique_codes").type == "Set[int]"
+
+    address = field_by_name(request, "address")
+    assert address.type == "Dict[str, Any]"
+    assert address.nested_fields is not None
+    assert [field.name for field in address.nested_fields] == [
+        "street",
+        "postal_code",
+    ]
+    assert address.nested_fields[0].validation == {"min_length": 2}
+
+    stored_definition = request.model_dump(mode="json")
+    rebuilt = model_from_extraction_request(stored_definition)
+    value = rebuilt(
+        record_id="64c26f2a-8fd0-4ef8-b1ec-7969ebbe91cb",
+        issued_on="2026-07-11",
+        tags=["one", "two"],
+        unique_codes=[1, 1, 2],
+        address={"street": "Main Street"},
+    )
+
+    assert value.record_id == UUID("64c26f2a-8fd0-4ef8-b1ec-7969ebbe91cb")
+    assert value.amount == Decimal("1.50")
+    assert value.issued_on == date(2026, 7, 11)
+    assert value.unique_codes == {1, 2}
+    assert value.address.street == "Main Street"
+
+    dumped = value.model_dump(mode="json")
+    assert dumped["record_id"] == "64c26f2a-8fd0-4ef8-b1ec-7969ebbe91cb"
+    assert dumped["amount"] == "1.50"
+    assert dumped["issued_on"] == "2026-07-11"
+    assert sorted(dumped["unique_codes"]) == [1, 2]
+    json.dumps(dumped)
+
+    python_dump = value.model_dump()
+    assert python_dump["amount"] == Decimal("1.50")
+    assert python_dump["issued_on"] == date(2026, 7, 11)
+
+
+def test_extraction_request_methods_preserve_the_original_definition():
+    request = ExtractionRequest(
+        model_name="Invoice",
+        model_description="Invoice fields",
+        fields=[
+            ModelField(
+                name="invoice_number",
+                type="string",
+                description="Unique invoice number",
+                required=True,
+                nullable=False,
+                validation={"min_length": 2},
+            )
+        ],
+    )
+
+    model = model_from_extraction_request(request)
+    restored = model_to_extraction_request(model)
+
+    assert restored == request
+    assert model(invoice_number="A1").invoice_number == "A1"
+
+
+def test_model_conversion_does_not_inherit_base_model_documentation():
+    class UndocumentedModel(BaseModel):
+        value: str
+
+    request = model_to_extraction_request(UndocumentedModel)
+
+    assert request.model_description == ""
+
+
+def test_model_conversion_rejects_executable_model_behavior():
+    class ValidatedModel(BaseModel):
+        value: str
+
+        @field_validator("value")
+        @classmethod
+        def normalize_value(cls, value: str) -> str:
+            return value.strip()
+
+    with pytest.raises(ModelGenerationError, match="Custom validators"):
+        model_to_extraction_request(ValidatedModel)
+
+
+def test_model_conversion_rejects_default_factories():
+    class FactoryModel(BaseModel):
+        values: list[str] = Field(default_factory=list)
+
+    with pytest.raises(ModelGenerationError, match="Default factories"):
+        model_to_extraction_request(FactoryModel)