feat: support union and optional arguments

README.md

@@ -124,6 +124,37 @@ This will open a browser window with the Streamlit UI where users can input valu
 | --------------------------------- | ---------------------------- |
 | ![](examples/vectoradd_jax/screenshots/vec-b.png)        | ![](examples/vectoradd_jax/screenshots/plot.png)    |
 
+## 🔀 Union Type Support
+
+`tesseract-streamlit` supports Pydantic union types (e.g., `int | str`, `float | None`) with automatic type inference:
+
+### Supported Union Patterns
+
+* **Optional numbers**: `int | None`, `float | None` - Rendered as text inputs (not number inputs) with placeholder text "Leave blank if not needed". This allows the field to truly be empty. The input is parsed as an integer or float when provided.
+* **Optional strings**: `str | None` - Rendered as text inputs with placeholder text. Leave blank to pass `None`.
+* **Mixed scalar types**: `int | float`, `float | str`, `int | str | None` - Rendered as text inputs with automatic type casting.
+
+### Auto-Casting Behavior
+
+Union type fields use a text input with automatic type detection:
+
+1. **Integers**: Input like `42` or `-23` is parsed as `int`
+2. **Floats**: Input like `3.14`, `-0.5`, or `1e-5` is parsed as `float`
+3. **Strings**: Any other input is treated as a string
+4. **None**: Leaving the field blank (for optional fields) passes `None`
+
+**Example:**
+```python
+class InputSchema(BaseModel):
+    threshold: float | str  # Can accept 0.5 (float) or "auto" (string)
+    count: int | None = None  # Optional integer, blank input passes None
+```
+
+### Limitations
+
+* **Collections of complex types**: Unions like `Model | list[Model]` or `float | list[float]` are not yet supported. These are deferred to a future release.
+* **No specialized widgets**: Union fields always use text inputs. For example, `int | float` uses a text input instead of a number input with spinners.
+
 ## ⚠️ Current Limitations
 
 While `tesseract-streamlit` supports Tesseracts with an `InputSchema` formed with arbitrary nesting of Pydantic models, it **does not yet support** nesting Pydantic models **inside native Python collection types** such as:

tesseract_streamlit/parse.py

@@ -201,7 +201,7 @@ def _resolve_refs(
 
     Recursively descends into the nested dictionary, locating '$ref'
     keys. Where these are found, the URI path to elsewhere in the
-    dictionary is resolved, yielding a dictionary. This dictionary
+    dictionary is resolved, yieldin a dictionary. This dictionary
     is then merged with the parent dictionary where the '$ref' key was
     located.
 
@@ -280,6 +280,7 @@ class _InputField(typing.TypedDict):
     title: str
     description: str
     ancestors: list[str]
+    optional: bool
     default: NotRequired[typing.Any]
     number_constraints: NumberConstraints
 
@@ -289,6 +290,77 @@ def _key_to_title(key: str) -> str:
     return key.replace("_", " ").title()
 
 
+def _is_union_type(field_data: dict[str, typing.Any]) -> bool:
+    """Check if a field uses union type (anyOf).
+
+    Args:
+        field_data: dictionary of data representing the field.
+
+    Returns:
+        True if the field uses anyOf (union type), False otherwise.
+    """
+    return "anyOf" in field_data and "type" not in field_data
+
+
+def _resolve_union_type(field_data: dict[str, typing.Any]) -> tuple[str, bool]:
+    """Resolve union type, preserving base type for simple optionals.
+
+    Args:
+        field_data: dictionary of data representing the field with anyOf.
+
+    Returns:
+        tuple[str, bool]: (resolved_type, is_optional)
+
+    Resolution logic:
+    - If union is `Type | None`, return (Type, True)
+    - If union is numeric primitives + arrays, return ("array", is_optional)
+    - If union has multiple non-null types, return ("union", is_optional)
+
+    Raises:
+        ValueError: If union includes composite types (not supported)
+    """
+    any_of = field_data.get("anyOf", [])
+
+    # Check for composite types in union (unsupported)
+    has_composite = any(
+        "$ref" in member or ("properties" in member and "type" not in member)
+        for member in any_of
+    )
+    if has_composite:
+        raise ValueError(
+            "Unions including composite types (e.g., Model | int, Model1 | Model2) "
+            "are not currently supported. Use one of the composite types directly."
+        )
+
+    # Collect non-null types
+    types = []
+    for member in any_of:
+        if "type" in member:
+            member_type = member["type"]
+            if member_type != "null":
+                types.append(member_type)
+
+    # Check if null is in the union
+    is_optional = any(
+        member.get("type") == "null" for member in any_of if "type" in member
+    )
+
+    # If only one non-null type, return it (e.g., int | None → integer)
+    if len(types) == 1:
+        return (types[0], is_optional)
+
+    # Check if union is numeric primitives + arrays (e.g., float | list[float])
+    non_array_types = [t for t in types if t != "array"]
+    has_array = "array" in types
+    is_all_numeric = all(t in ("integer", "number") for t in non_array_types)
+
+    if has_array and is_all_numeric and non_array_types:
+        return ("array", is_optional)
+
+    # Multiple non-null types → union
+    return ("union", is_optional)
+
+
 def _format_field(
     field_key: str,
     field_data: dict[str, typing.Any],
@@ -308,25 +380,49 @@ def _format_field(
     Returns:
         Formatted input field data.
     """
+    # Handle union types (anyOf)
+    is_optional = False
+    if _is_union_type(field_data):
+        resolved_type, is_optional = _resolve_union_type(field_data)
+        # Inject resolved type into field_data so rest of function works normally
+        field_data = {**field_data, "type": resolved_type}
+
+    # Check for collections of composite types (unsupported)
+    if field_data.get("type") == "array":
+        items = field_data.get("items", {})
+        if "$ref" in items or ("properties" in items and "type" not in items):
+            raise ValueError(
+                f"Collections of composite types (e.g., list[Model]) are not currently "
+                f"supported for field '{field_key}'. Consider restructuring your schema."
+            )
+
     field = _InputField(
         type=field_data["type"],
         title=field_data.get("title", field_key) if use_title else field_key,
         description=field_data.get("description", None),
         ancestors=[*ancestors, field_key],
+        optional=is_optional,
     )
 
     if "properties" not in field_data:  # signals a Python primitive type
         if field["type"] != "object":
             default_val = field_data.get("default", None)
-            if (field_data["type"] == "string") and (default_val is None):
+            # For non-optional strings, convert None default to empty string
+            if (
+                (field_data["type"] == "string")
+                and (default_val is None)
+                and not is_optional
+            ):
                 default_val = ""
             field["default"] = default_val
+            # Only add number_constraints if constraints actually exist
             if field_data["type"] in ("number", "integer"):
-                field["number_constraints"] = {
-                    "min_value": field_data.get("minimum", None),
-                    "max_value": field_data.get("maximum", None),
-                    "step": field_data.get("multipleOf", None),
-                }
+                if any(k in field_data for k in ("minimum", "maximum", "multipleOf")):
+                    field["number_constraints"] = {
+                        "min_value": field_data.get("minimum", None),
+                        "max_value": field_data.get("maximum", None),
+                        "step": field_data.get("multipleOf", None),
+                    }
         return field
     field["title"] = _key_to_title(field_key) if use_title else field_key
     if ARRAY_PROPS <= set(field_data["properties"]):
@@ -424,6 +520,7 @@ class JinjaField(typing.TypedDict):
     type: str
     description: str
     title: str
+    optional: bool
     default: NotRequired[typing.Any]
     number_constraints: NumberConstraints