fh-pydantic-form 0.3.18
a library to turn any pydantic BaseModel object into a fasthtml/monsterui input form
Requires Python: >=3.12
Keywords: fasthtml, forms, monsterui, pydantic, ui, web

# fh-pydantic-form

[![PyPI](https://img.shields.io/pypi/v/fh-pydantic-form)](https://pypi.org/project/fh-pydantic-form/)
[![GitHub](https://img.shields.io/github/stars/Marcura/fh-pydantic-form?style=social)](https://github.com/Marcura/fh-pydantic-form)

**Generate HTML forms from Pydantic models for your FastHTML applications.**

`fh-pydantic-form` simplifies creating web forms for [FastHTML](https://github.com/AnswerDotAI/fasthtml) by automatically generating the necessary HTML input elements based on your Pydantic model definitions. It integrates seamlessly with  and leverages [MonsterUI](https://github.com/AnswerDotAI/monsterui) components for styling. This makes it ideal for annotation workflows for structured outputs: when the schema updates, so does your annotation app.

<img width="1072" alt="image" src="https://github.com/user-attachments/assets/9e189266-0118-4de2-a35c-1118f11b0581" />




<details >
    <summary>show demo screen recording</summary>
<video src="https://private-user-images.githubusercontent.com/27999937/462832274-a00096d9-47ee-485b-af0a-e74838ec6c6d.mp4" controls="controls">
</video>
</details>

## Table of Contents
1. [Purpose](#purpose)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Key Features](#key-features)
5. [Spacing & Styling](#spacing--styling)
6. [Working with Lists](#working-with-lists)
7. [Nested Models](#nested-models)
8. [Literal & Enum Fields](#literal--enum-fields)
9. [Initial Values & Enum Parsing](#initial-values--enum-parsing)
10. [Disabling & Excluding Fields](#disabling--excluding-fields)
11. [Refreshing & Resetting](#refreshing--resetting)
12. [Label Colors](#label-colors)
13. [Metrics & Highlighting](#metrics--highlighting)
14. [ComparisonForm](#comparisonform)
15. [Schema Drift Resilience](#schema-drift-resilience)
16. [Custom Renderers](#custom-renderers)
17. [API Reference](#api-reference)
18. [Contributing](#contributing)

## Purpose

-   **Reduce Boilerplate:** Automatically render form inputs (text, number, checkbox, select, date, time, etc.) based on Pydantic field types and annotations.
-   **Data Validation:** Leverage Pydantic's validation rules directly from form submissions.
-   **Nested Structures:** Support for nested Pydantic models and lists of models/simple types with accordion UI.
-   **Dynamic Lists:** Built-in HTMX endpoints and JavaScript for adding, deleting, and reordering items in lists within the form.
-   **Customization:** Easily register custom renderers for specific Pydantic types or fields.
-   **Robust Schema Handling:** Gracefully handles model changes and missing fields in initial data.

## Installation

You can install `fh-pydantic-form` using either `pip` or `uv`.

**Using pip:**

```bash
pip install fh-pydantic-form
```

Using uv:
```bash
uv add fh-pydantic-form
```

This will also install necessary dependencies like `pydantic`, `python-fasthtml`, and `monsterui`.

## Quick Start

```python
# examples/simple_example.py
import fasthtml.common as fh
import monsterui.all as mui
from pydantic import BaseModel, ValidationError

# 1. Import the form renderer
from fh_pydantic_form import PydanticForm

app, rt = fh.fast_app(
    hdrs=[
        mui.Theme.blue.headers(),
        # Add list_manipulation_js() if using list fields
        # from fh_pydantic_form import list_manipulation_js
        # list_manipulation_js(),
    ],
    pico=False, # Using MonsterUI, not PicoCSS
    live=True,  # Enable live reload for development
)

# 2. Define your Pydantic model
class SimpleModel(BaseModel):
    """Model representing a simple form"""
    name: str = "Default Name"
    age: int
    is_active: bool = True

# 3. Create a form renderer instance
#    - 'my_form': Unique name for the form (used for prefixes and routes)
#    - SimpleModel: The Pydantic model class
form_renderer = PydanticForm("my_form", SimpleModel)

# (Optional) Register list manipulation routes if your model has List fields
# form_renderer.register_routes(app)

# 4. Define routes
@rt("/")
def get():
    """Display the form"""
    return fh.Div(
        mui.Container(
            mui.Card(
                mui.CardHeader("Simple Pydantic Form"),
                mui.CardBody(
                    # Use MonsterUI Form component for structure
                    mui.Form(
                        # Render the inputs using the renderer
                        form_renderer.render_inputs(),
                        # Add standard form buttons
                        fh.Div(
                            mui.Button("Submit", type="submit", cls=mui.ButtonT.primary),
                            form_renderer.refresh_button("🔄"),
                            form_renderer.reset_button("↩️"),
                            cls="mt-4 flex items-center gap-2",
                        ),
                        # HTMX attributes for form submission
                        hx_post="/submit_form",
                        hx_target="#result", # Target div for response
                        hx_swap="innerHTML",
                        # Set a unique ID for the form itself for refresh/reset inclusion
                        id=f"{form_renderer.name}-form",
                    )
                ),
            ),
            # Div to display validation results
            fh.Div(id="result"),
        ),
    )

@rt("/submit_form")
async def post_submit_form(req):
    """Handle form submission and validation"""
    try:
        # 5. Validate the request data against the model
        validated_data: SimpleModel = await form_renderer.model_validate_request(req)

        # Success: Display the validated data
        return mui.Card(
            mui.CardHeader(fh.H3("Validation Successful")),
            mui.CardBody(
                fh.Pre(
                    validated_data.model_dump_json(indent=2),
                )
            ),
            cls="mt-4",
        )
    except ValidationError as e:
        # Validation Error: Display the errors
        return mui.Card(
            mui.CardHeader(fh.H3("Validation Error", cls="text-red-500")),
            mui.CardBody(
                fh.Pre(
                    e.json(indent=2),
                )
            ),
            cls="mt-4",
        )

if __name__ == "__main__":
    fh.serve()
```

## Key Features

-   **Automatic Field Rendering:** Handles `str`, `int`, `float`, `bool`, `date`, `time`, `Optional`, `Literal`, nested `BaseModel`s, and `List`s out-of-the-box.
-   **Sensible Defaults:** Uses appropriate HTML5 input types (`text`, `number`, `date`, `time`, `checkbox`, `select`).
-   **Labels & Placeholders:** Generates labels from field names (converting snake_case to Title Case) and basic placeholders.
-   **Descriptions as Tooltips:** Uses `Field(description=...)` from Pydantic to create tooltips (`uk-tooltip` via UIkit).
-   **Required Fields:** Automatically adds the `required` attribute based on field definitions (considering `Optional` and defaults).
-   **Disabled Fields:** Disable the whole form with `disabled=True` or disable specific fields with `disabled_fields`
-   **Collapsible Nested Models:** Renders nested Pydantic models in accordion-style components for better form organization and space management.
-   **List Manipulation:**
    -   Renders lists of simple types or models in accordion-style cards with an enhanced UI.
    -   Provides HTMX endpoints (registered via `register_routes`) for adding and deleting list items.
    -   Includes JavaScript (`list_manipulation_js()`) for client-side reordering (moving items up/down).
    -   Click list field labels to toggle all items open/closed.
-   **Form Refresh & Reset:**
    -   Provides HTMX-powered "Refresh" and "Reset" buttons (`form_renderer.refresh_button()`, `form_renderer.reset_button()`).
    -   Refresh updates list item summaries or other dynamic parts without full page reload.
    -   Reset reverts the form to its initial values.
-   **Custom Renderers:** Register your own `BaseFieldRenderer` subclasses for specific Pydantic types or complex field logic using `FieldRendererRegistry` or by passing `custom_renderers` during `PydanticForm` initialization.
-   **Form Data Parsing:** Includes logic (`form_renderer.parse` and `form_renderer.model_validate_request`) to correctly parse submitted form data (handling prefixes, list indices, nested structures, boolean checkboxes, etc.) back into a dictionary suitable for Pydantic validation.

## Spacing & Styling

`fh-pydantic-form` ships with two spacing presets to fit different UI requirements:

| Theme | Purpose | Usage |
|-------|---------|-------|
| **normal** (default) | Comfortable margins & borders – great for desktop forms | `PydanticForm(..., spacing="normal")` |
| **compact** | Ultra-dense UIs, mobile layouts, or forms with many fields | `PydanticForm(..., spacing="compact")` |

```python
# Example: side-by-side normal vs compact forms
form_normal = PydanticForm("normal_form", MyModel, spacing="normal")
form_compact = PydanticForm("compact_form", MyModel, spacing="compact")
```


**Important:** The compact CSS is now scoped with `.fhpf-compact` classes and only affects form inputs, not layout containers. This prevents conflicts with your application's layout system.

## Working with Lists

When your Pydantic models contain `List[str]`, `List[int]`, or `List[BaseModel]` fields, `fh-pydantic-form` provides rich list manipulation capabilities:

### Basic Setup

```python
from fh_pydantic_form import PydanticForm, list_manipulation_js
from typing import List

app, rt = fh.fast_app(
    hdrs=[
        mui.Theme.blue.headers(),
        list_manipulation_js(),  # Required for list manipulation
    ],
    pico=False,
    live=True,
)

class ListModel(BaseModel):
    name: str = ""
    tags: List[str] = Field(["tag1", "tag2"])
    addresses: List[Address] = Field(default_factory=list)

form_renderer = PydanticForm("list_model", ListModel)
form_renderer.register_routes(app)  # Register HTMX endpoints
```

### Dynamic Forms (template routes)

If you create many forms dynamically (e.g. one per table row) and **can’t** register routes for every unique form name, you can register routes once on a “template” form and have dynamic forms route list/refresh actions through it via `template_name`.

```python
# Register routes once at startup
template = PydanticForm("doc_template", Doc)
template.register_routes(app)

@rt("/")
def index():
    # Dynamic form name per row/request
    form = PydanticForm(
        form_name="row_1",
        model_class=Doc,
        template_name="doc_template",
    )
    return mui.Form(
        fh.Div(
            form.refresh_button(),
            form.reset_button(),
            cls="flex gap-2 mb-3",
        ),
        form.render_inputs(),
    )
```

How it works:
- List/refresh URLs are generated under `/form/<template_name>/...`.
- The actual form instance name is sent as `fhpf_form_name`, so the template routes can render the correct prefixes.

### List Features

- **Add Items:** Each list has an "Add Item" button that creates new entries
- **Delete Items:** Each list item has a delete button with confirmation
- **Reorder Items:** Move items up/down with arrow buttons
- **Toggle All:** Click the list field label to expand/collapse all items at once
- **Refresh Display:** Use the 🔄 icon next to list labels to update item summaries
- **Smart Defaults:** New items are created with sensible default values

The list manipulation uses HTMX for seamless updates without page reloads, and includes JavaScript for client-side reordering.

## Nested Models

Nested Pydantic models are automatically rendered in collapsible accordion components:

```python
class Address(BaseModel):
    street: str = "123 Main St"
    city: str = "Anytown"
    is_billing: bool = False

class User(BaseModel):
    name: str
    address: Address  # Rendered as collapsible accordion
    backup_addresses: List[Address]  # List of accordions
```

**Key behaviors:**
- Nested models inherit `disabled` and `spacing` settings from the parent form
- Field prefixes are automatically managed (e.g., `user_address_street`)
- Accordions are open by default for better user experience
- Schema drift is handled gracefully - missing fields use defaults, unknown fields are ignored

## Literal & Enum Fields

`fh-pydantic-form` provides comprehensive support for choice-based fields through `Literal`, `Enum`, and `IntEnum` types, all automatically rendered as dropdown selects:

### Literal Fields

```python
from typing import Literal, Optional

class OrderModel(BaseModel):
    # Required Literal field - only defined choices available
    shipping_method: Literal["STANDARD", "EXPRESS", "OVERNIGHT"] = "STANDARD"
    
    # Optional Literal field - includes "-- None --" option
    category: Optional[Literal["ELECTRONICS", "CLOTHING", "BOOKS", "OTHER"]] = None
```

### Enum Fields

```python
from enum import Enum, IntEnum

class OrderStatus(Enum):
    """Order status enum with string values."""
    PENDING = "pending"
    CONFIRMED = "confirmed" 
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    CANCELLED = "cancelled"

class Priority(IntEnum):
    """Priority levels using IntEnum for numeric ordering."""
    LOW = 1
    MEDIUM = 2
    HIGH = 3
    URGENT = 4

class OrderModel(BaseModel):
    # Required Enum field with default
    status: OrderStatus = OrderStatus.PENDING
    
    # Optional Enum field without default
    payment_method: Optional[PaymentMethod] = None
    
    # Required IntEnum field with default
    priority: Priority = Priority.MEDIUM
    
    # Optional IntEnum field without default
    urgency_level: Optional[Priority] = Field(
        None, description="Override priority for urgent orders"
    )
    
    # Enum field without default (required)
    fulfillment_status: OrderStatus = Field(
        ..., description="Current fulfillment status"
    )
```

### Field Rendering Behavior

| Field Type | Required | Optional | Notes |
|------------|----------|----------|-------|
| **Literal** | Shows only defined choices | Includes "-- None --" option | String values displayed as-is |
| **Enum** | Shows enum member values | Includes "-- None --" option | Displays `enum.value` in dropdown |
| **IntEnum** | Shows integer values | Includes "-- None --" option | Maintains numeric ordering |

**Key features:**
- **Automatic dropdown generation** for all choice-based field types
- **Proper value handling** - enum values are correctly parsed during form submission
- **Optional field support** - includes None option when fields are Optional
- **Field descriptions** become tooltips on hover
- **Default value selection** - dropdowns pre-select the appropriate default value

## Initial Values & Enum Parsing

`fh-pydantic-form` intelligently parses initial values from dictionaries, properly converting strings and integers to their corresponding enum types:

### Setting Initial Values

```python
# Example initial values from a dictionary
initial_values_dict = {
    "shipping_method": "EXPRESS",      # Literal value as string
    "category": "ELECTRONICS",         # Optional Literal value
    "status": "shipped",               # Enum value (parsed to OrderStatus.SHIPPED)
    "payment_method": "paypal",        # Optional Enum (parsed to PaymentMethod.PAYPAL)
    "priority": 3,                     # IntEnum as integer (parsed to Priority.HIGH)
    "urgency_level": 4,                # Optional IntEnum as integer (parsed to Priority.URGENT)
    "fulfillment_status": "confirmed"  # Required Enum (parsed to OrderStatus.CONFIRMED)
}

# Create form with initial values
form_renderer = PydanticForm("order_form", OrderModel, initial_values=initial_values_dict)
```

### Parsing Behavior

The form automatically handles conversion between different value formats:

| Input Type | Target Type | Example | Result |
|------------|-------------|---------|--------|
| String | Enum | `"shipped"` | `OrderStatus.SHIPPED` |
| String | Optional[Enum] | `"paypal"` | `PaymentMethod.PAYPAL` |
| Integer | IntEnum | `3` | `Priority.HIGH` |
| Integer | Optional[IntEnum] | `4` | `Priority.URGENT` |
| String | Literal | `"EXPRESS"` | `"EXPRESS"` (unchanged) |

**Benefits:**
- **Flexible data sources** - works with database records, API responses, or any dictionary
- **Type safety** - ensures enum values are valid during parsing
- **Graceful handling** - invalid enum values are passed through for Pydantic validation
- **Consistent behavior** - same parsing logic for required and optional fields

### Example Usage

```python
@rt("/")
def get():
    return mui.Form(
        form_renderer.render_inputs(),  # Pre-populated with parsed enum values
        fh.Div(
            mui.Button("Submit", type="submit", cls=mui.ButtonT.primary),
            form_renderer.refresh_button("🔄"),
            form_renderer.reset_button("↩️"),  # Resets to initial parsed values
            cls="mt-4 flex items-center gap-2",
        ),
        hx_post="/submit_order",
        hx_target="#result",
        id=f"{form_renderer.name}-form",
    )

@rt("/submit_order")
async def post_submit_order(req):
    try:
        # Validates and converts form data back to proper enum types
        validated_order: OrderModel = await form_renderer.model_validate_request(req)
        
        # Access enum properties
        print(f"Status: {validated_order.status.value} ({validated_order.status.name})")
        print(f"Priority: {validated_order.priority.value} ({validated_order.priority.name})")
        
        return success_response(validated_order)
    except ValidationError as e:
        return error_response(e)
```

This makes it easy to work with enum-based forms when loading data from databases, APIs, or configuration files.

## Disabling & Excluding Fields

### Disabling Fields

You can disable the entire form or specific fields:

```python
# Disable all fields
form_renderer = PydanticForm("my_form", FormModel, disabled=True)

# Disable specific fields only
form_renderer = PydanticForm(
    "my_form",
    FormModel,
    disabled_fields=["field1", "field3"]
)
```

### Excluding Fields

Exclude specific fields from being rendered in the form:

```python
form_renderer = PydanticForm(
    "my_form",
    FormModel,
    exclude_fields=["internal_field", "computed_field"]
)
```

**Important:** When fields are excluded from the UI, `fh-pydantic-form` automatically injects their default values during form parsing and validation. This ensures:

- **Hidden fields with defaults** are still included in the final validated data
- **Required fields without defaults** will still cause validation errors if not provided elsewhere
- **Default factories** are executed to provide computed default values
- **Nested BaseModel defaults** are converted to dictionaries for consistency

This automatic default injection means you can safely exclude fields that shouldn't be user-editable while maintaining data integrity.

### SkipJsonSchema Fields

`fh-pydantic-form` provides advanced handling for `SkipJsonSchema` fields with selective visibility control. By default, fields marked with `SkipJsonSchema` are hidden from forms, but you can selectively show specific ones using the `keep_skip_json_fields` parameter.

```python
from pydantic.json_schema import SkipJsonSchema

class DocumentModel(BaseModel):
    title: str
    content: str
    
    # Hidden by default - system fields
    document_id: SkipJsonSchema[str] = Field(
        default_factory=lambda: f"doc_{uuid4().hex[:12]}",
        description="Internal document ID"
    )
    created_at: SkipJsonSchema[datetime.datetime] = Field(
        default_factory=datetime.datetime.now,
        description="Creation timestamp"
    )
    version: SkipJsonSchema[int] = Field(
        default=1, 
        description="Document version"
    )

# Normal form - all SkipJsonSchema fields hidden
form_normal = PydanticForm("doc_form", DocumentModel)

# Admin form - selectively show some SkipJsonSchema fields
form_admin = PydanticForm(
    "admin_form", 
    DocumentModel,
    keep_skip_json_fields=[
        "document_id",  # Show document ID
        "version",      # Show version number
        # created_at remains hidden
    ]
)
```

#### Nested SkipJsonSchema Fields

The feature supports dot notation for nested objects and list items:

```python
class Address(BaseModel):
    street: str
    city: str
    # Hidden system field
    internal_id: SkipJsonSchema[str] = Field(default_factory=lambda: f"addr_{uuid4().hex[:8]}")

class UserModel(BaseModel):
    name: str
    main_address: Address
    other_addresses: List[Address]

# Show specific nested SkipJsonSchema fields
form = PydanticForm(
    "user_form",
    UserModel,
    keep_skip_json_fields=[
        "main_address.internal_id",        # Show main address ID
        "other_addresses.internal_id",     # Show all address IDs in the list
    ]
)
```

**Key Features:**
- **Hidden by default:** SkipJsonSchema fields are automatically excluded from forms
- **Selective visibility:** Use `keep_skip_json_fields` to show specific fields
- **Nested support:** Access nested fields with dot notation (`"main_address.internal_id"`)
- **List support:** Show fields in all list items (`"addresses.internal_id"`)
- **Smart defaults:** Non-kept fields use model defaults, kept fields retain initial values
- **Admin interfaces:** Perfect for admin panels or debugging where you need to see system fields

See `examples/complex_example.py` for a comprehensive demonstration of SkipJsonSchema field handling.

## Refreshing & Resetting

Forms support dynamic refresh and reset functionality:

```python
mui.Form(
    form_renderer.render_inputs(),
    fh.Div(
        mui.Button("Submit", type="submit", cls=mui.ButtonT.primary),
        form_renderer.refresh_button("🔄 Refresh"),  # Update display
        form_renderer.reset_button("↩️ Reset"),      # Restore initial values
        cls="mt-4 flex items-center gap-2",
    ),
    # ... rest of form setup
)
```

- **Refresh button** updates the form display based on current values (useful for updating list item summaries)
- **Reset button** restores all fields to their initial values with confirmation
- Both use HTMX for seamless updates without page reloads

**Dynamic forms via `template_name`:**
- Refresh is routed through the template form and scoped to the specific instance via `fhpf_form_name`.
- `reset_button()` becomes client-side (restores the initial HTML snapshot). Ensure `list_manipulation_js()` is included on the page.


## Label Colors

Customize the appearance of field labels with the `label_colors` parameter:

```python
form_renderer = PydanticForm(
    "my_form",
    MyModel,
    label_colors={
        "name": "text-blue-600",    # Tailwind CSS class
        "score": "#E12D39",        # Hex color value
        "status": "text-green-500", # Another Tailwind class
    },
)
```

**Supported formats:**
- **Tailwind CSS classes:** `"text-blue-600"`, `"text-red-500"`, etc.
- **Hex color values:** `"#FF0000"`, `"#0066CC"`, etc.
- **CSS color names:** `"red"`, `"blue"`, `"darkgreen"`, etc.

This can be useful for e.g. highlighting the values of different fields in a pdf with different highlighting colors matching the form input label color. 

## Metrics & Highlighting

`fh-pydantic-form` provides a powerful metrics system for visual highlighting of form fields based on extraction quality scores and confidence assessments. This is particularly useful for evaluating LLM structured output extraction, comparing generated data against ground truth, and building quality assessment interfaces.

<img width="796" alt="image" src="https://github.com/user-attachments/assets/df2f8623-991d-45b1-80d8-5c7239187a74" />


### Basic Metrics Usage

```python
from fh_pydantic_form import PydanticForm

# Define metrics for your form fields
metrics_dict = {
    "title": {
        "metric": 0.95,
        "comment": "Excellent title quality - clear and engaging"
    },
    "rating": {
        "metric": 0.3,
        "comment": "Low rating needs attention"
    },
    "status": {
        "metric": 0.0,
        "comment": "Critical status issue - requires immediate review"
    }
}

# Create form with metrics
form_renderer = PydanticForm(
    "my_form",
    MyModel,
    metrics_dict=metrics_dict
)
```

### Metrics Dictionary Structure

Each field can have the following metrics properties:

| Property | Type | Description |
|----------|------|-------------|
| `metric` | `float` or `str` | Numeric score (0.0-1.0) or string assessment |
| `color` | `str` | Custom color (overrides automatic color-coding) |
| `comment` | `str` | Tooltip text shown on hover |

### Automatic Color Coding

Numeric metrics are automatically color-coded:

- **1.0**: Bright green (perfect score)
- **0.5-1.0**: Medium green (good range)
- **0.0-0.5**: Dark red (needs attention)
- **0.0**: Bright red (critical issue)

```python
metrics_dict = {
    "field1": {"metric": 1.0, "comment": "Perfect!"},      # Bright green
    "field2": {"metric": 0.8, "comment": "Very good"},     # Medium green
    "field3": {"metric": 0.3, "comment": "Needs work"},    # Dark red
    "field4": {"metric": 0.0, "comment": "Critical"},      # Bright red
}
```

### Custom Colors

Override automatic colors with custom values:

```python
metrics_dict = {
    "status": {
        "metric": 0.0,
        "color": "purple",  # Custom color overrides red
        "comment": "Status requires special attention"
    },
    "priority": {
        "metric": 1.0,
        "color": "#FF6B35",  # Custom hex color
        "comment": "High priority with custom highlight"
    }
}
```

### String Metrics

Use string values for qualitative assessments:

```python
metrics_dict = {
    "validation_status": {
        "metric": "NEEDS_REVIEW",
        "color": "#F59E0B",  # Amber color
        "comment": "Requires human review"
    },
    "data_quality": {
        "metric": "EXCELLENT",
        "color": "#10B981",  # Green color
        "comment": "Data quality exceeds standards"
    }
}
```

### Nested Field Metrics

Support for nested objects and list items:

```python
metrics_dict = {
    # Nested object fields
    "author.name": {
        "metric": 0.95,
        "comment": "Author name perfectly formatted"
    },
    "author.email": {
        "metric": 0.9,
        "comment": "Email format excellent"
    },
    
    # List item metrics
    "tags[0]": {
        "metric": 1.0,
        "comment": "First tag is perfect"
    },
    "tags[1]": {
        "metric": 0.8,
        "comment": "Second tag very good"
    },
    
    # Complex nested paths
    "author.addresses[0].street": {
        "metric": 1.0,
        "comment": "Street address perfectly formatted"
    },
    "author.addresses[1].city": {
        "metric": 0.1,
        "color": "teal",
        "comment": "City has verification problems"
    }
}
```

### Practical Use Cases

**LLM Structured Output Evaluation:**
```python
# Evaluate LLM extraction quality against ground truth
extraction_metrics = {
    "product.name": {
        "metric": 0.9,
        "comment": "Name extracted with minor formatting issue: missing space"
    },
    "product.category": {
        "metric": 0.0,
        "comment": "Critical error: LLM misclassified Electronics instead of Sports"
    },
    "key_features": {
        "metric": 0.6,
        "comment": "LLM missed 2 of 5 key features from source text"
    },
    "extraction_confidence": {
        "metric": 1.0,
        "comment": "LLM confidence score accurately reflects actual performance"
    }
}
```

**Document Processing Quality:**
```python
# Highlight extraction quality from documents
doc_extraction_metrics = {
    "invoice_number": {
        "metric": 1.0,
        "comment": "Invoice number perfectly extracted from PDF"
    },
    "line_items": {
        "metric": 0.75,
        "comment": "3/4 line items extracted correctly"
    },
    "total_amount": {
        "metric": 0.0,
        "comment": "Amount extraction failed - currency symbol confusion"
    }
}
```

See `examples/metrics_example.py` for a comprehensive demonstration of all metrics features.

## ComparisonForm

The `ComparisonForm` component provides side-by-side comparison of two related forms, perfect for evaluating LLM structured output against ground truth, annotation correction workflows, and comparing extraction results.


<img width="1177" alt="image" src="https://github.com/user-attachments/assets/75020059-0d4d-4519-9c71-70a082d3242e" />

### Basic Usage

```python
from fh_pydantic_form import PydanticForm, ComparisonForm

# Create two forms to compare
left_form = PydanticForm(
    "ground_truth",
    ProductModel,
    initial_values=annotated_ground_truth,
    disabled=False  # Editable for annotation correction
)

right_form = PydanticForm(
    "llm_output", 
    ProductModel,
    initial_values=llm_extracted_data,
    disabled=True,  # Read-only LLM output
    metrics_dict=extraction_quality_metrics
)

# Create comparison form
comparison_form = ComparisonForm(
    name="extraction_evaluation",
    left_form=left_form,
    right_form=right_form,
    left_label="📝 Ground Truth (Editable)",
    right_label="🤖 LLM Output (with Quality Scores)"
)
```

### Required JavaScript

Include the comparison form JavaScript in your app headers:

```python
from fh_pydantic_form import comparison_form_js

app, rt = fh.fast_app(
    hdrs=[
        mui.Theme.blue.headers(),
        comparison_form_js(),  # Required for comparison forms
    ],
    pico=False,
    live=True,
)
```

### Complete Example

```python
@rt("/")
def get():
    return fh.Div(
        mui.Container(
            mui.Card(
                mui.CardHeader(
                    fh.H1("LLM Extraction Evaluation")
                ),
                mui.CardBody(
                    # Render the comparison form
                    comparison_form.form_wrapper(
                        fh.Div(
                            comparison_form.render_inputs(),
                            
                            # Action buttons
                            fh.Div(
                                mui.Button(
                                    "Update Ground Truth",
                                    type="submit",
                                    hx_post="/update_ground_truth",
                                    hx_target="#result"
                                ),
                                comparison_form.left_reset_button("Reset Left"),
                                comparison_form.left_refresh_button("Refresh Left"),
                                cls="mt-4 flex gap-2"
                            ),
                            
                            fh.Div(id="result", cls="mt-4")
                        )
                    )
                )
            )
        )
    )

@rt("/update_ground_truth")
async def post_update_ground_truth(req):
    # Validate left form (ground truth side)
    validated = await comparison_form.left_form.model_validate_request(req)
    
    # Process the ground truth update
    return success_response(validated)

# Register routes for both forms
comparison_form.register_routes(app)
```

### Key Features
- **Aligned fields** input fields are horizontally aligned for easy comparison.
- **Synchronized Accordions**: Expanding/collapsing sections syncs between both forms
- **Independent Controls**: Separate refresh and reset buttons for each side
- **Metrics Integration**: Right side typically shows LLM output quality scores
- **Flexible Layout**: Responsive design works on desktop and mobile
- **Form Validation**: Standard validation works with either form
- **Intelligent List Copying**: Copy lists between forms with automatic length adjustment
- **Multiple Comparisons per Page**: Copy + accordion sync is scoped to each comparison grid

### Dynamic ComparisonForms (template routes)

If you create many ComparisonForms dynamically (e.g., one per table row) and **can't** register routes for every unique form, you can register routes once on a "template" ComparisonForm and have dynamic instances route refresh/reset actions through it via `template_name`.

```python
# Register routes once at startup via a template ComparisonForm
template_left = PydanticForm("template_left", Doc)
template_right = PydanticForm("template_right", Doc)
template_comp = ComparisonForm(
    name="compare_template",  # Routes registered under this name
    left_form=template_left,
    right_form=template_right,
    # template_name defaults to "compare_template"
)
template_comp.register_routes(app)

# Dynamic ComparisonForms per row/request - NO register_routes() needed
for row_id in row_ids:
    left = PydanticForm(
        f"left_{row_id}", Doc,
        template_name="template_left",  # Reuse PydanticForm routes
    )
    right = PydanticForm(
        f"right_{row_id}", Doc,
        template_name="template_right",
    )
    comparison = ComparisonForm(
        name=f"compare_{row_id}",
        left_form=left,
        right_form=right,
        template_name="compare_template",  # Reference the template's name
    )
    # Render comparison.render_inputs() - routes are shared via template_name
```

How it works:
- Refresh URLs are generated under `/compare/<template_name>/...`
- The actual form instance name is sent as `fhpf_form_name`, so the template routes can render the correct prefixes
- Same pattern as `PydanticForm.template_name` for list manipulation routes
- For dynamic instances, reset buttons use the client-side snapshot reset so each row resets to its own initial values

### Copying Between Forms

The ComparisonForm provides granular copy functionality at multiple levels. When you enable copy buttons (via `copy_left=True` or `copy_right=True`), each field, nested model, and list item gets its own copy button for maximum flexibility:

```python
# Enable copy buttons (copy FROM right TO left)
comparison_form = ComparisonForm(
    name="extraction_evaluation",
    left_form=left_form,
    right_form=right_form,
    left_label="Ground Truth",
    right_label="LLM Output",
    copy_left=True,  # Show copy buttons on right form to copy TO left
)
```

**Copy Granularity Levels:**

The copy feature works at five different levels of granularity:

1. **Individual Fields** - Copy a single field value (e.g., `name`, `price`, `status`)

2. **Nested BaseModel (Entire Object)** - Copy all fields within a nested model at once

3. **Individual Fields in Nested Models** - Copy a specific field within a nested object

4. **Full List Fields** - Copy entire lists with automatic length adjustment

5. **Individual List Items** - Add a single item from one list to another


### Common Patterns

**LLM Output Evaluation:**
```python
# Left: Editable ground truth
# Right: Read-only LLM output with extraction quality metrics
truth_form = PydanticForm(..., disabled=False, metrics_dict={})
llm_form = PydanticForm(..., disabled=True, metrics_dict=extraction_metrics)
```

**Document Extraction Comparison:**
```python
# Left: Manual annotation
# Right: Automated LLM extraction
manual_form = PydanticForm(..., initial_values=manual_annotation)
auto_form = PydanticForm(..., initial_values=llm_extraction, metrics_dict=quality_scores)
```

**Annotation Correction Workflow:**
```python
# Left: Correctable ground truth
# Right: LLM output with confidence scores
ground_truth_form = PydanticForm(..., disabled=False)
llm_output_form = PydanticForm(..., disabled=True, metrics_dict=confidence_scores)
```

See `examples/comparison_example.py` for a complete LLM extraction evaluation interface demonstration.

## Setting Initial Values

You can set initial form values of the form by passing a model instance or dictionary:

```python
initial_data = MyModel(name="John", tags=["happy", "joy"])
form_renderer = PydanticForm("my_form", MyModel, initial_values=initial_data)


initial_data_dict = {"name": "John"} 
form_renderer = PydanticForm("my_form", MyModel, initial_values=initial_values_dict)
```

The dictionary does not have to be complete, and we try to handle schema drift gracefully. If you exclude fields from the form, we fill those fields with the initial_values or the default values.

### Reusing Form Configuration with Different Values

The `with_initial_values()` method allows you to create a new form instance with the same configuration but different initial values:

```python
# Create a base form configuration
base_form = PydanticForm(
    "product_form",
    ProductModel,
    disabled_fields=["id"],
    label_colors={"name": "text-blue-600", "price": "text-green-600"},
    spacing="compact"
)

# Create forms with different initial values using the same configuration
form_for_product_a = base_form.with_initial_values({"name": "Product A", "price": 29.99})
form_for_product_b = base_form.with_initial_values({"name": "Product B", "price": 45.50})

# Or with model instances
existing_product = ProductModel(name="Existing Product", price=19.99)
form_for_existing = base_form.with_initial_values(existing_product)
```

This is particularly useful for:
- **Editing workflows** where you need the same form configuration for different records
- **Template forms** where you want to reuse styling and field configurations
- **Bulk operations** where you process multiple items with the same form structure



### Schema Drift Resilience

`fh-pydantic-form` gracefully handles model evolution and schema changes:

Initial values can come from **older or newer** versions of your model – unknown fields are ignored gracefully and missing fields use defaults.

```python
# Your model evolves over time
class UserModel(BaseModel):
    name: str
    email: str           # Added in v2
    phone: Optional[str] # Added in v3

# Old data still works
old_data = {"name": "John"}  # Missing newer fields
form = PydanticForm("user", UserModel, initial_values=old_data)

# Newer data works too
new_data = {"name": "Jane", "email": "jane@example.com", "phone": "555-1234", "removed_field": "ignored"}
form = PydanticForm("user", UserModel, initial_values=new_data)
```

**Benefits:**
- **Backward compatibility:** Old data structures continue to work
- **Forward compatibility:** Unknown fields are silently ignored
- **Graceful degradation:** Missing fields fall back to model defaults
- **Production stability:** No crashes during rolling deployments

## Custom Renderers

The library is extensible through custom field renderers for specialized input types:

```python
from fh_pydantic_form.field_renderers import BaseFieldRenderer
from fh_pydantic_form import FieldRendererRegistry

class CustomDetail(BaseModel):
    value: str = "Default value"
    confidence: Literal["HIGH", "MEDIUM", "LOW"] = "MEDIUM"

    def __str__(self) -> str:
        return f"{self.value} ({self.confidence})"

class CustomDetailFieldRenderer(BaseFieldRenderer):
    """Display value input and dropdown side by side"""

    def render_input(self):
        value_input = fh.Div(
            mui.Input(
                value=self.value.get("value", ""),
                id=f"{self.field_name}_value",
                name=f"{self.field_name}_value",
                placeholder=f"Enter {self.original_field_name.replace('_', ' ')} value",
                cls="uk-input w-full",  
            ),
            cls="flex-grow",
        )

        confidence_options = [
            fh.Option(
                opt, value=opt, selected=(opt == self.value.get("confidence", "MEDIUM"))
            )
            for opt in ["HIGH", "MEDIUM", "LOW"]
        ]

        confidence_select = mui.Select(
            *confidence_options,
            id=f"{self.field_name}_confidence",
            name=f"{self.field_name}_confidence",
            cls_wrapper="w-[110px] min-w-[110px] flex-shrink-0",
        )

        return fh.Div(
            value_input,
            confidence_select,
            cls="flex items-start g