schemez 0.1.1__tar.gz → 0.2.2__tar.gz

{schemez-0.1.1 → schemez-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: schemez
-Version: 0.1.1
+Version: 0.2.2
 Summary: Pydantic shim for config stuff
 Project-URL: Documentation, https://phil65.github.io/schemez/
 Project-URL: Source, https://github.com/phil65/schemez
@@ -49,6 +49,11 @@ Requires-Python: >=3.12
 Requires-Dist: griffe>=1.7.3
 Requires-Dist: pydantic
 Requires-Dist: universal-pathlib>=0.2.6
+Provides-Extra: ai
+Requires-Dist: anyenv>=0.4.14; extra == 'ai'
+Requires-Dist: llmling-agent; extra == 'ai'
+Provides-Extra: yaml
+Requires-Dist: yamling; extra == 'yaml'
 Description-Content-Type: text/markdown
 
 # Schemez

{schemez-0.1.1 → schemez-0.2.2}/pyproject.toml

@@ -27,9 +27,9 @@ classifiers = [
     "Topic :: Documentation",
     "Topic :: Software Development",
     "Topic :: Utilities",
-    "Typing :: Typed","Framework :: Pydantic",
+    "Typing :: Typed",
+    "Framework :: Pydantic",
     "Framework :: Pydantic :: 2",
-
 ]
 keywords = []
 requires-python = ">=3.12"
@@ -41,8 +41,9 @@ dependencies = [
     "universal-pathlib>=0.2.6",
 ]
 
-[project-optional-dependencies]
+[project.optional-dependencies]
 yaml = ["yamling"]
+ai = ["llmling-agent", "anyenv>=0.4.14"]
 
 [tool.uv]
 default-groups = ["dev", "lint", "docs"]
@@ -158,7 +159,7 @@ select = [
     # "TD",   # flake8-todos
     "T10", # flake8-debugger
     # "T20",  # flake8-print
-    "TC", # flake8-type-checking
+    "TC",  # flake8-type-checking
     "TID", # flake8-tidy-imports
     "TRY", # tryceratops
     "UP",  # PyUpgrade
@@ -198,7 +199,7 @@ ignore = [
     # "PLR2004", # Magic values instead of named consts
     "SLF001", # Private member accessed
     "TRY003", # Avoid specifying long messages outside the exception class
-    "TC006", # runtime-cast-value
+    "TC006",  # runtime-cast-value
 ]
 
 [tool.ruff.lint.flake8-quotes]

schemez-0.2.2/src/schemez/__init__.py

@@ -0,0 +1,27 @@
+__version__ = "0.2.2"
+
+
+from schemez.schema import Schema
+from schemez.code import PythonCode, JSONCode, TOMLCode, YAMLCode
+from schemez.schemadef.schemadef import (
+    SchemaDef,
+    SchemaField,
+    ImportedSchemaDef,
+    InlineSchemaDef,
+)
+from schemez.pydantic_types import ModelIdentifier, ModelTemperature, MimeType
+
+__all__ = [
+    "ImportedSchemaDef",
+    "InlineSchemaDef",
+    "JSONCode",
+    "MimeType",
+    "ModelIdentifier",
+    "ModelTemperature",
+    "PythonCode",
+    "Schema",
+    "SchemaDef",
+    "SchemaField",
+    "TOMLCode",
+    "YAMLCode",
+]

schemez-0.2.2/src/schemez/helpers.py

@@ -0,0 +1,171 @@
+"""Helpers for BaseModels."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+
+StrPath = str | os.PathLike[str]
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def import_callable(path: str) -> Callable[..., Any]:
+    """Import a callable from a dotted path.
+
+    Supports both dot and colon notation:
+    - Dot notation: module.submodule.Class.method
+    - Colon notation: module.submodule:Class.method
+
+    Args:
+        path: Import path using dots and/or colon
+
+    Raises:
+        ValueError: If path cannot be imported or result isn't callable
+    """
+    if not path:
+        msg = "Import path cannot be empty"
+        raise ValueError(msg)
+
+    # Normalize path - replace colon with dot if present
+    normalized_path = path.replace(":", ".")
+    parts = normalized_path.split(".")
+
+    # Try importing progressively smaller module paths
+    for i in range(len(parts), 0, -1):
+        try:
+            # Try current module path
+            module_path = ".".join(parts[:i])
+            module = importlib.import_module(module_path)
+
+            # Walk remaining parts as attributes
+            obj = module
+            for part in parts[i:]:
+                obj = getattr(obj, part)
+
+            # Check if we got a callable
+            if callable(obj):
+                return obj
+
+            msg = f"Found object at {path} but it isn't callable"
+            raise ValueError(msg)
+
+        except ImportError:
+            # Try next shorter path
+            continue
+        except AttributeError:
+            # Attribute not found - try next shorter path
+            continue
+
+    # If we get here, no import combination worked
+    msg = f"Could not import callable from path: {path}"
+    raise ValueError(msg)
+
+
+def import_class(path: str) -> type:
+    """Import a class from a dotted path.
+
+    Args:
+        path: Dot-separated path to the class
+
+    Returns:
+        The imported class
+
+    Raises:
+        ValueError: If path is invalid or doesn't point to a class
+    """
+    try:
+        obj = import_callable(path)
+        if not isinstance(obj, type):
+            msg = f"{path} is not a class"
+            raise TypeError(msg)  # noqa: TRY301
+    except Exception as exc:
+        msg = f"Failed to import class from {path}"
+        raise ValueError(msg) from exc
+    else:
+        return obj
+
+
+def merge_models[T: BaseModel](base: T, overlay: T) -> T:
+    """Deep merge two Pydantic models."""
+    if not isinstance(overlay, type(base)):
+        msg = f"Cannot merge different types: {type(base)} and {type(overlay)}"
+        raise TypeError(msg)
+
+    merged_data = base.model_dump()
+    overlay_data = overlay.model_dump(exclude_none=True)
+    for field_name, field_value in overlay_data.items():
+        base_value = merged_data.get(field_name)
+
+        match (base_value, field_value):
+            case (list(), list()):
+                merged_data[field_name] = [
+                    *base_value,
+                    *(item for item in field_value if item not in base_value),
+                ]
+            case (dict(), dict()):
+                merged_data[field_name] = base_value | field_value
+            case _:
+                merged_data[field_name] = field_value
+
+    return base.__class__.model_validate(merged_data)
+
+
+def resolve_type_string(type_string: str, safe: bool = True) -> type:
+    """Convert a string representation to an actual Python type.
+
+    Args:
+        type_string: String representation of a type (e.g. "list[str]", "int")
+        safe: If True, uses a limited set of allowed types. If False, allows any valid
+              Python type expression but has potential security implications
+              if input is untrusted
+
+    Returns:
+        The corresponding Python type
+
+    Raises:
+        ValueError: If the type string cannot be resolved
+    """
+    if safe:
+        # Create a safe context with just the allowed types
+        type_context = {
+            "str": str,
+            "int": int,
+            "float": float,
+            "bool": bool,
+            "list": list,
+            "dict": dict,
+            "set": set,
+            "tuple": tuple,
+            "Any": Any,
+            # Add other safe types as needed
+        }
+
+        try:
+            return eval(type_string, {"__builtins__": {}}, type_context)
+        except Exception as e:
+            msg = f"Failed to resolve type {type_string} in safe mode"
+            raise ValueError(msg) from e
+    else:  # unsafe mode
+        # Import common typing modules to make them available
+        import collections.abc
+        import typing
+
+        # Create a context with full typing module available
+        type_context = {
+            **vars(typing),
+            **vars(collections.abc),
+            **{t.__name__: t for t in __builtins__.values() if isinstance(t, type)},  # type: ignore
+        }
+
+        try:
+            return eval(type_string, {"__builtins__": {}}, type_context)
+        except Exception as e:
+            msg = f"Failed to resolve type {type_string} in unsafe mode"
+            raise ValueError(msg) from e

schemez-0.2.2/src/schemez/pydantic_types.py

@@ -0,0 +1,42 @@
+"""Custom field types with 'field_type' metadata for UI rendering hints."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+
+ModelIdentifier = Annotated[
+    str,
+    Field(
+        json_schema_extra={"field_type": "model_identifier"},
+        pattern=r"^[a-zA-Z0-9\-]+(/[a-zA-Z0-9\-]+)*(:[\w\-\.]+)?$",
+        examples=["openai:gpt-o1-mini", "anthropic/claude-3-opus"],
+        description="Identifier for an AI model, optionally including provider.",
+    ),
+]
+
+ModelTemperature = Annotated[
+    float,
+    Field(
+        json_schema_extra={"field_type": "temperature", "step": 0.1},
+        ge=0.0,
+        le=2.0,
+        description=(
+            "Controls randomness in model responses.\n"
+            "Lower values are more deterministic, higher values more creative"
+        ),
+        examples=[0.0, 0.7, 1.0],
+    ),
+]
+
+MimeType = Annotated[
+    str,
+    Field(
+        json_schema_extra={"field_type": "mime_type"},
+        pattern=r"^[a-z]+/[a-z0-9\-+.]+$",
+        examples=["text/plain", "application/pdf", "image/jpeg", "application/json"],
+        description="Standard MIME type identifying file formats and content types",
+    ),
+]

schemez-0.2.2/src/schemez/schema.py

@@ -0,0 +1,246 @@
+"""Configuration models for Schemez."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Literal, Self
+
+import anyenv
+from pydantic import BaseModel, ConfigDict
+import upath
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from llmling_agent.agent.agent import AgentType
+    from llmling_agent.models.content import BaseContent
+
+
+StrPath = str | os.PathLike[str]
+SourceType = Literal["pdf", "image"]
+
+DEFAULT_SYSTEM_PROMPT = "You are a schema extractor for {name} BaseModels."
+DEFAULT_USER_PROMPT = "Extract information from this document:"
+
+
+class Schema(BaseModel):
+    """Base class configuration models.
+
+    Provides:
+    - Common Pydantic settings
+    - YAML serialization
+    - Basic merge functionality
+    """
+
+    model_config = ConfigDict(extra="forbid", use_attribute_docstrings=True)
+
+    def merge(self, other: Self) -> Self:
+        """Merge with another instance by overlaying its non-None values."""
+        from schemez.helpers import merge_models
+
+        return merge_models(self, other)
+
+    @classmethod
+    def from_yaml(cls, content: str, inherit_path: StrPath | None = None) -> Self:
+        """Create from YAML string."""
+        import yamling
+
+        data = yamling.load_yaml(content, resolve_inherit=inherit_path or False)
+        return cls.model_validate(data)
+
+    @classmethod
+    def for_function(
+        cls, func: Callable[..., Any], *, name: str | None = None
+    ) -> type[Schema]:
+        """Create a schema model from a function's signature.
+
+        Args:
+            func: The function to create a schema from
+            name: Optional name for the model
+
+        Returns:
+            A new schema model class based on the function parameters
+        """
+        from schemez.convert import get_function_model
+
+        return get_function_model(func, name=name)
+
+    @classmethod
+    def from_vision_llm_sync(
+        cls,
+        file_content: bytes,
+        source_type: SourceType = "pdf",
+        model: str = "google-gla:gemini-2.0-flash",
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        user_prompt: str = DEFAULT_USER_PROMPT,
+        provider: AgentType = "pydantic_ai",
+    ) -> Self:
+        """Create a schema model from a document using AI.
+
+        Args:
+            file_content: The document content to create a schema from
+            source_type: The type of the document
+            model: The AI model to use for schema extraction
+            system_prompt: The system prompt to use for schema extraction
+            user_prompt: The user prompt to use for schema extraction
+            provider: The provider to use for schema extraction
+
+        Returns:
+            A new schema model class based on the document
+        """
+        from llmling_agent import Agent, ImageBase64Content, PDFBase64Content
+
+        if source_type == "pdf":
+            content: BaseContent = PDFBase64Content.from_bytes(file_content)
+        else:
+            content = ImageBase64Content.from_bytes(file_content)
+        agent = Agent[None](  # type:ignore[var-annotated]
+            model=model,
+            system_prompt=system_prompt.format(name=cls.__name__),
+            provider=provider,
+        ).to_structured(cls)
+        chat_message = anyenv.run_sync(agent.run(user_prompt, content))
+        return chat_message.content
+
+    @classmethod
+    async def from_vision_llm(
+        cls,
+        file_content: bytes,
+        source_type: SourceType = "pdf",
+        model: str = "google-gla:gemini-2.0-flash",
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        user_prompt: str = DEFAULT_USER_PROMPT,
+        provider: AgentType = "pydantic_ai",
+    ) -> Self:
+        """Create a schema model from a document using AI.
+
+        Args:
+            file_content: The document content to create a schema from
+            source_type: The type of the document
+            model: The AI model to use for schema extraction
+            system_prompt: The system prompt to use for schema extraction
+            user_prompt: The user prompt to use for schema extraction
+            provider: The provider to use for schema extraction
+
+        Returns:
+            A new schema model class based on the document
+        """
+        from llmling_agent import Agent, ImageBase64Content, PDFBase64Content
+
+        if source_type == "pdf":
+            content: BaseContent = PDFBase64Content.from_bytes(file_content)
+        else:
+            content = ImageBase64Content.from_bytes(file_content)
+        agent = Agent[None](  # type:ignore[var-annotated]
+            model=model,
+            system_prompt=system_prompt.format(name=cls.__name__),
+            provider=provider,
+        ).to_structured(cls)
+        chat_message = await agent.run(user_prompt, content)
+        return chat_message.content
+
+    @classmethod
+    def from_llm_sync(
+        cls,
+        text: str,
+        model: str = "google-gla:gemini-2.0-flash",
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        user_prompt: str = DEFAULT_USER_PROMPT,
+        provider: AgentType = "pydantic_ai",
+    ) -> Self:
+        """Create a schema model from a text snippet using AI.
+
+        Args:
+            text: The text to create a schema from
+            model: The AI model to use for schema extraction
+            system_prompt: The system prompt to use for schema extraction
+            user_prompt: The user prompt to use for schema extraction
+            provider: The provider to use for schema extraction
+
+        Returns:
+            A new schema model class based on the document
+        """
+        from llmling_agent import Agent
+
+        agent = Agent[None](  # type:ignore[var-annotated]
+            model=model,
+            system_prompt=system_prompt.format(name=cls.__name__),
+            provider=provider,
+        ).to_structured(cls)
+        chat_message = anyenv.run_sync(agent.run(user_prompt, text))
+        return chat_message.content
+
+    @classmethod
+    async def from_llm(
+        cls,
+        text: str,
+        model: str = "google-gla:gemini-2.0-flash",
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        user_prompt: str = DEFAULT_USER_PROMPT,
+        provider: AgentType = "pydantic_ai",
+    ) -> Self:
+        """Create a schema model from a text snippet using AI.
+
+        Args:
+            text: The text to create a schema from
+            model: The AI model to use for schema extraction
+            system_prompt: The system prompt to use for schema extraction
+            user_prompt: The user prompt to use for schema extraction
+            provider: The provider to use for schema extraction
+
+        Returns:
+            A new schema model class based on the document
+        """
+        from llmling_agent import Agent
+
+        agent = Agent[None](  # type:ignore[var-annotated]
+            model=model,
+            system_prompt=system_prompt.format(name=cls.__name__),
+            provider=provider,
+        ).to_structured(cls)
+        chat_message = await agent.run(user_prompt, text)
+        return chat_message.content
+
+    @classmethod
+    def for_class_ctor(cls, target_cls: type) -> type[Schema]:
+        """Create a schema model from a class constructor.
+
+        Args:
+            target_cls: The class whose constructor to convert
+
+        Returns:
+            A new schema model class based on the constructor parameters
+        """
+        from schemez.convert import get_ctor_basemodel
+
+        return get_ctor_basemodel(target_cls)
+
+    def model_dump_yaml(self) -> str:
+        """Dump configuration to YAML string."""
+        import yamling
+
+        return yamling.dump_yaml(self.model_dump(exclude_none=True))
+
+    def save(self, path: StrPath, overwrite: bool = False) -> None:
+        """Save configuration to a YAML file.
+
+        Args:
+            path: Path to save the configuration to
+            overwrite: Whether to overwrite an existing file
+
+        Raises:
+            OSError: If file cannot be written
+            ValueError: If path is invalid
+        """
+        yaml_str = self.model_dump_yaml()
+        try:
+            file_path = upath.UPath(path)
+            if file_path.exists() and not overwrite:
+                msg = f"File already exists: {path}"
+                raise FileExistsError(msg)  # noqa: TRY301
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(yaml_str)
+        except Exception as exc:
+            msg = f"Failed to save configuration to {path}"
+            raise ValueError(msg) from exc

schemez-0.2.2/src/schemez/schemadef/schemadef.py

@@ -0,0 +1,120 @@
+"""Models for schema fields and definitions."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, create_model
+
+from schemez import Schema, helpers
+
+
+class SchemaField(Schema):
+    """Field definition for inline response types.
+
+    Defines a single field in an inline response definition, including:
+    - Data type specification
+    - Optional description
+    - Validation constraints
+
+    Used by InlineSchemaDef to structure response fields.
+    """
+
+    type: str
+    """Data type of the response field"""
+
+    description: str | None = None
+    """Optional description of what this field represents"""
+
+    constraints: dict[str, Any] = Field(default_factory=dict)
+    """Optional validation constraints for the field"""
+
+
+class BaseSchemaDef(Schema):
+    """Base class for response definitions."""
+
+    type: str = Field(init=False)
+
+    description: str | None = None
+    """A description for this response definition."""
+
+
+class InlineSchemaDef(BaseSchemaDef):
+    """Inline definition of schema.
+
+    Allows defining response types directly in the configuration using:
+    - Field definitions with types and descriptions
+    - Optional validation constraints
+    - Custom field descriptions
+
+    Example:
+        schemas:
+          BasicResult:
+            type: inline
+            fields:
+              success: {type: bool, description: "Operation success"}
+              message: {type: str, description: "Result details"}
+    """
+
+    type: Literal["inline"] = Field("inline", init=False)
+    """Inline response definition."""
+
+    fields: dict[str, SchemaField]
+    """A dictionary containing all fields."""
+
+    def get_schema(self) -> type[Schema]:  # type: ignore
+        """Create Pydantic model from inline definition."""
+        fields = {}
+        for name, field in self.fields.items():
+            python_type = helpers.resolve_type_string(field.type)
+            if not python_type:
+                msg = f"Unsupported field type: {field.type}"
+                raise ValueError(msg)
+
+            field_info = Field(description=field.description, **(field.constraints))
+            fields[name] = (python_type, field_info)
+
+        cls_name = self.description or "ResponseType"
+        return create_model(cls_name, **fields, __base__=Schema, __doc__=self.description)  # type: ignore[call-overload]
+
+
+class ImportedSchemaDef(BaseSchemaDef):
+    """Response definition that imports an existing Pydantic model.
+
+    Allows using externally defined Pydantic models as response types.
+    Benefits:
+    - Reuse existing model definitions
+    - Full Python type support
+    - Complex validation logic
+    - IDE support for imported types
+
+    Example:
+        responses:
+          AnalysisResult:
+            type: import
+            import_path: myapp.models.AnalysisResult
+    """
+
+    type: Literal["import"] = Field("import", init=False)
+    """Import-path based response definition."""
+
+    import_path: str
+    """The path to the pydantic model to use as the response type."""
+
+    # mypy is confused about "type"
+    # TODO: convert BaseModel to Schema?
+    def get_schema(self) -> type[BaseModel]:  # type: ignore
+        """Import and return the model class."""
+        try:
+            model_class = helpers.import_class(self.import_path)
+            if not issubclass(model_class, BaseModel):
+                msg = f"{self.import_path} must be a Pydantic model"
+                raise TypeError(msg)  # noqa: TRY301
+        except Exception as e:
+            msg = f"Failed to import response type {self.import_path}"
+            raise ValueError(msg) from e
+        else:
+            return model_class
+
+
+SchemaDef = Annotated[InlineSchemaDef | ImportedSchemaDef, Field(discriminator="type")]

schemez-0.1.1/src/schemez/__init__.py

@@ -1,7 +0,0 @@
-__version__ = "0.1.1"
-
-
-from schemez.schema import Schema
-from schemez.code import PythonCode, JSONCode, TOMLCode, YAMLCode
-
-__all__ = ["JSONCode", "PythonCode", "Schema", "TOMLCode", "YAMLCode"]

schemez-0.1.1/src/schemez/helpers.py

@@ -1,35 +0,0 @@
-"""Helpers for BaseModels."""
-
-from __future__ import annotations
-
-import os
-
-from pydantic import BaseModel
-
-
-StrPath = str | os.PathLike[str]
-
-
-def merge_models[T: BaseModel](base: T, overlay: T) -> T:
-    """Deep merge two Pydantic models."""
-    if not isinstance(overlay, type(base)):
-        msg = f"Cannot merge different types: {type(base)} and {type(overlay)}"
-        raise TypeError(msg)
-
-    merged_data = base.model_dump()
-    overlay_data = overlay.model_dump(exclude_none=True)
-    for field_name, field_value in overlay_data.items():
-        base_value = merged_data.get(field_name)
-
-        match (base_value, field_value):
-            case (list(), list()):
-                merged_data[field_name] = [
-                    *base_value,
-                    *(item for item in field_value if item not in base_value),
-                ]
-            case (dict(), dict()):
-                merged_data[field_name] = base_value | field_value
-            case _:
-                merged_data[field_name] = field_value
-
-    return base.__class__.model_validate(merged_data)

schemez-0.1.1/src/schemez/schema.py

@@ -1,102 +0,0 @@
-"""Configuration models for Schemez."""
-
-from __future__ import annotations
-
-import os
-from typing import TYPE_CHECKING, Any, Self
-
-from pydantic import BaseModel, ConfigDict
-import upath
-
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-
-StrPath = str | os.PathLike[str]
-
-
-class Schema(BaseModel):
-    """Base class configuration models.
-
-    Provides:
-    - Common Pydantic settings
-    - YAML serialization
-    - Basic merge functionality
-    """
-
-    model_config = ConfigDict(extra="forbid", use_attribute_docstrings=True)
-
-    def merge(self, other: Self) -> Self:
-        """Merge with another instance by overlaying its non-None values."""
-        from schemez.helpers import merge_models
-
-        return merge_models(self, other)
-
-    @classmethod
-    def from_yaml(cls, content: str, inherit_path: StrPath | None = None) -> Self:
-        """Create from YAML string."""
-        import yamling
-
-        data = yamling.load_yaml(content, resolve_inherit=inherit_path or False)
-        return cls.model_validate(data)
-
-    @classmethod
-    def for_function(
-        cls, func: Callable[..., Any], *, name: str | None = None
-    ) -> type[Schema]:
-        """Create a schema model from a function's signature.
-
-        Args:
-            func: The function to create a schema from
-            name: Optional name for the model
-
-        Returns:
-            A new schema model class based on the function parameters
-        """
-        from schemez.convert import get_function_model
-
-        return get_function_model(func, name=name)
-
-    @classmethod
-    def for_class_ctor(cls, target_cls: type) -> type[Schema]:
-        """Create a schema model from a class constructor.
-
-        Args:
-            target_cls: The class whose constructor to convert
-
-        Returns:
-            A new schema model class based on the constructor parameters
-        """
-        from schemez.convert import get_ctor_basemodel
-
-        return get_ctor_basemodel(target_cls)
-
-    def model_dump_yaml(self) -> str:
-        """Dump configuration to YAML string."""
-        import yamling
-
-        return yamling.dump_yaml(self.model_dump(exclude_none=True))
-
-    def save(self, path: StrPath, overwrite: bool = False) -> None:
-        """Save configuration to a YAML file.
-
-        Args:
-            path: Path to save the configuration to
-            overwrite: Whether to overwrite an existing file
-
-        Raises:
-            OSError: If file cannot be written
-            ValueError: If path is invalid
-        """
-        yaml_str = self.model_dump_yaml()
-        try:
-            file_path = upath.UPath(path)
-            if file_path.exists() and not overwrite:
-                msg = f"File already exists: {path}"
-                raise FileExistsError(msg)  # noqa: TRY301
-            file_path.parent.mkdir(parents=True, exist_ok=True)
-            file_path.write_text(yaml_str)
-        except Exception as exc:
-            msg = f"Failed to save configuration to {path}"
-            raise ValueError(msg) from exc