{"id":34085873,"url":"https://github.com/marcura/fh-pydantic-form","last_synced_at":"2026-01-19T10:00:43.268Z","repository":{"id":289537022,"uuid":"965970378","full_name":"Marcura/fh-pydantic-form","owner":"Marcura","description":"Generate HTML forms from Pydantic models for your FastHTML application","archived":false,"fork":false,"pushed_at":"2026-01-15T13:41:46.000Z","size":736,"stargazers_count":37,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-15T17:37:02.361Z","etag":null,"topics":["fasthtml","forms","monsterui","pydantic"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/fh-pydantic-form","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Marcura.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-14T07:45:10.000Z","updated_at":"2026-01-15T13:28:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"67d1bdf1-f75e-4d25-9307-bdc44e28b92b","html_url":"https://github.com/Marcura/fh-pydantic-form","commit_stats":null,"previous_names":["marcura/fh-pydantic-form"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/Marcura/fh-pydantic-form","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marcura%2Ffh-pydantic-form","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marcura%2Ffh-pydantic-form/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marcura%2Ffh-pydantic-form/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marcura%2Ffh-pydantic-form/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Marcura","download_url":"https://codeload.github.com/Marcura/fh-pydantic-form/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marcura%2Ffh-pydantic-form/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28565047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T08:53:44.001Z","status":"ssl_error","status_checked_at":"2026-01-19T08:52:40.245Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fasthtml","forms","monsterui","pydantic"],"created_at":"2025-12-14T13:16:31.396Z","updated_at":"2026-01-19T10:00:43.258Z","avatar_url":"https://github.com/Marcura.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fh-pydantic-form\n\n[![PyPI](https://img.shields.io/pypi/v/fh-pydantic-form)](https://pypi.org/project/fh-pydantic-form/)\n[![GitHub](https://img.shields.io/github/stars/Marcura/fh-pydantic-form?style=social)](https://github.com/Marcura/fh-pydantic-form)\n\n**Generate HTML forms from Pydantic models for your FastHTML applications.**\n\n`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.\n\n\u003cimg width=\"1072\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9e189266-0118-4de2-a35c-1118f11b0581\" /\u003e\n\n\n\n\n\u003cdetails \u003e\n    \u003csummary\u003eshow demo screen recording\u003c/summary\u003e\n\u003cvideo src=\"https://private-user-images.githubusercontent.com/27999937/462832274-a00096d9-47ee-485b-af0a-e74838ec6c6d.mp4\" controls=\"controls\"\u003e\n\u003c/video\u003e\n\u003c/details\u003e\n\n## Table of Contents\n1. [Purpose](#purpose)\n2. [Installation](#installation)\n3. [Quick Start](#quick-start)\n4. [Key Features](#key-features)\n5. [Spacing \u0026 Styling](#spacing--styling)\n6. [Working with Lists](#working-with-lists)\n7. [Nested Models](#nested-models)\n8. [Literal \u0026 Enum Fields](#literal--enum-fields)\n9. [Initial Values \u0026 Enum Parsing](#initial-values--enum-parsing)\n10. [Disabling \u0026 Excluding Fields](#disabling--excluding-fields)\n11. [Refreshing \u0026 Resetting](#refreshing--resetting)\n12. [Label Colors](#label-colors)\n13. [Metrics \u0026 Highlighting](#metrics--highlighting)\n14. [ComparisonForm](#comparisonform)\n15. [Schema Drift Resilience](#schema-drift-resilience)\n16. [Custom Renderers](#custom-renderers)\n17. [API Reference](#api-reference)\n18. [Contributing](#contributing)\n\n## Purpose\n\n-   **Reduce Boilerplate:** Automatically render form inputs (text, number, checkbox, select, date, time, etc.) based on Pydantic field types and annotations.\n-   **Data Validation:** Leverage Pydantic's validation rules directly from form submissions.\n-   **Nested Structures:** Support for nested Pydantic models and lists of models/simple types with accordion UI.\n-   **Dynamic Lists:** Built-in HTMX endpoints and JavaScript for adding, deleting, and reordering items in lists within the form.\n-   **Customization:** Easily register custom renderers for specific Pydantic types or fields.\n-   **Robust Schema Handling:** Gracefully handles model changes and missing fields in initial data.\n\n## Installation\n\nYou can install `fh-pydantic-form` using either `pip` or `uv`.\n\n**Using pip:**\n\n```bash\npip install fh-pydantic-form\n```\n\nUsing uv:\n```bash\nuv add fh-pydantic-form\n```\n\nThis will also install necessary dependencies like `pydantic`, `python-fasthtml`, and `monsterui`.\n\n## Quick Start\n\n```python\n# examples/simple_example.py\nimport fasthtml.common as fh\nimport monsterui.all as mui\nfrom pydantic import BaseModel, ValidationError\n\n# 1. Import the form renderer\nfrom fh_pydantic_form import PydanticForm\n\napp, rt = fh.fast_app(\n    hdrs=[\n        mui.Theme.blue.headers(),\n        # Add list_manipulation_js() if using list fields\n        # from fh_pydantic_form import list_manipulation_js\n        # list_manipulation_js(),\n    ],\n    pico=False, # Using MonsterUI, not PicoCSS\n    live=True,  # Enable live reload for development\n)\n\n# 2. Define your Pydantic model\nclass SimpleModel(BaseModel):\n    \"\"\"Model representing a simple form\"\"\"\n    name: str = \"Default Name\"\n    age: int\n    is_active: bool = True\n\n# 3. Create a form renderer instance\n#    - 'my_form': Unique name for the form (used for prefixes and routes)\n#    - SimpleModel: The Pydantic model class\nform_renderer = PydanticForm(\"my_form\", SimpleModel)\n\n# (Optional) Register list manipulation routes if your model has List fields\n# form_renderer.register_routes(app)\n\n# 4. Define routes\n@rt(\"/\")\ndef get():\n    \"\"\"Display the form\"\"\"\n    return fh.Div(\n        mui.Container(\n            mui.Card(\n                mui.CardHeader(\"Simple Pydantic Form\"),\n                mui.CardBody(\n                    # Use MonsterUI Form component for structure\n                    mui.Form(\n                        # Render the inputs using the renderer\n                        form_renderer.render_inputs(),\n                        # Add standard form buttons\n                        fh.Div(\n                            mui.Button(\"Submit\", type=\"submit\", cls=mui.ButtonT.primary),\n                            form_renderer.refresh_button(\"🔄\"),\n                            form_renderer.reset_button(\"↩️\"),\n                            cls=\"mt-4 flex items-center gap-2\",\n                        ),\n                        # HTMX attributes for form submission\n                        hx_post=\"/submit_form\",\n                        hx_target=\"#result\", # Target div for response\n                        hx_swap=\"innerHTML\",\n                        # Set a unique ID for the form itself for refresh/reset inclusion\n                        id=f\"{form_renderer.name}-form\",\n                    )\n                ),\n            ),\n            # Div to display validation results\n            fh.Div(id=\"result\"),\n        ),\n    )\n\n@rt(\"/submit_form\")\nasync def post_submit_form(req):\n    \"\"\"Handle form submission and validation\"\"\"\n    try:\n        # 5. Validate the request data against the model\n        validated_data: SimpleModel = await form_renderer.model_validate_request(req)\n\n        # Success: Display the validated data\n        return mui.Card(\n            mui.CardHeader(fh.H3(\"Validation Successful\")),\n            mui.CardBody(\n                fh.Pre(\n                    validated_data.model_dump_json(indent=2),\n                )\n            ),\n            cls=\"mt-4\",\n        )\n    except ValidationError as e:\n        # Validation Error: Display the errors\n        return mui.Card(\n            mui.CardHeader(fh.H3(\"Validation Error\", cls=\"text-red-500\")),\n            mui.CardBody(\n                fh.Pre(\n                    e.json(indent=2),\n                )\n            ),\n            cls=\"mt-4\",\n        )\n\nif __name__ == \"__main__\":\n    fh.serve()\n```\n\n## Key Features\n\n-   **Automatic Field Rendering:** Handles `str`, `int`, `float`, `bool`, `date`, `time`, `Optional`, `Literal`, nested `BaseModel`s, and `List`s out-of-the-box.\n-   **Sensible Defaults:** Uses appropriate HTML5 input types (`text`, `number`, `date`, `time`, `checkbox`, `select`).\n-   **Labels \u0026 Placeholders:** Generates labels from field names (converting snake_case to Title Case) and basic placeholders.\n-   **Descriptions as Tooltips:** Uses `Field(description=...)` from Pydantic to create tooltips (`uk-tooltip` via UIkit).\n-   **Required Fields:** Automatically adds the `required` attribute based on field definitions (considering `Optional` and defaults).\n-   **Disabled Fields:** Disable the whole form with `disabled=True` or disable specific fields with `disabled_fields`\n-   **Collapsible Nested Models:** Renders nested Pydantic models in accordion-style components for better form organization and space management.\n-   **List Manipulation:**\n    -   Renders lists of simple types or models in accordion-style cards with an enhanced UI.\n    -   Provides HTMX endpoints (registered via `register_routes`) for adding and deleting list items.\n    -   Includes JavaScript (`list_manipulation_js()`) for client-side reordering (moving items up/down).\n    -   Click list field labels to toggle all items open/closed.\n-   **Form Refresh \u0026 Reset:**\n    -   Provides HTMX-powered \"Refresh\" and \"Reset\" buttons (`form_renderer.refresh_button()`, `form_renderer.reset_button()`).\n    -   Refresh updates list item summaries or other dynamic parts without full page reload.\n    -   Reset reverts the form to its initial values.\n-   **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.\n-   **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.\n\n## Spacing \u0026 Styling\n\n`fh-pydantic-form` ships with two spacing presets to fit different UI requirements:\n\n| Theme | Purpose | Usage |\n|-------|---------|-------|\n| **normal** (default) | Comfortable margins \u0026 borders – great for desktop forms | `PydanticForm(..., spacing=\"normal\")` |\n| **compact** | Ultra-dense UIs, mobile layouts, or forms with many fields | `PydanticForm(..., spacing=\"compact\")` |\n\n```python\n# Example: side-by-side normal vs compact forms\nform_normal = PydanticForm(\"normal_form\", MyModel, spacing=\"normal\")\nform_compact = PydanticForm(\"compact_form\", MyModel, spacing=\"compact\")\n```\n\n\n**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.\n\n## Working with Lists\n\nWhen your Pydantic models contain `List[str]`, `List[int]`, or `List[BaseModel]` fields, `fh-pydantic-form` provides rich list manipulation capabilities:\n\n### Basic Setup\n\n```python\nfrom fh_pydantic_form import PydanticForm, list_manipulation_js\nfrom typing import List\n\napp, rt = fh.fast_app(\n    hdrs=[\n        mui.Theme.blue.headers(),\n        list_manipulation_js(),  # Required for list manipulation\n    ],\n    pico=False,\n    live=True,\n)\n\nclass ListModel(BaseModel):\n    name: str = \"\"\n    tags: List[str] = Field([\"tag1\", \"tag2\"])\n    addresses: List[Address] = Field(default_factory=list)\n\nform_renderer = PydanticForm(\"list_model\", ListModel)\nform_renderer.register_routes(app)  # Register HTMX endpoints\n```\n\n### Dynamic Forms (template routes)\n\nIf 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`.\n\n```python\n# Register routes once at startup\ntemplate = PydanticForm(\"doc_template\", Doc)\ntemplate.register_routes(app)\n\n@rt(\"/\")\ndef index():\n    # Dynamic form name per row/request\n    form = PydanticForm(\n        form_name=\"row_1\",\n        model_class=Doc,\n        template_name=\"doc_template\",\n    )\n    return mui.Form(\n        fh.Div(\n            form.refresh_button(),\n            form.reset_button(),\n            cls=\"flex gap-2 mb-3\",\n        ),\n        form.render_inputs(),\n    )\n```\n\nHow it works:\n- List/refresh URLs are generated under `/form/\u003ctemplate_name\u003e/...`.\n- The actual form instance name is sent as `fhpf_form_name`, so the template routes can render the correct prefixes.\n\n### List Features\n\n- **Add Items:** Each list has an \"Add Item\" button that creates new entries\n- **Delete Items:** Each list item has a delete button with confirmation\n- **Reorder Items:** Move items up/down with arrow buttons\n- **Toggle All:** Click the list field label to expand/collapse all items at once\n- **Refresh Display:** Use the 🔄 icon next to list labels to update item summaries\n- **Smart Defaults:** New items are created with sensible default values\n\nThe list manipulation uses HTMX for seamless updates without page reloads, and includes JavaScript for client-side reordering.\n\n## Nested Models\n\nNested Pydantic models are automatically rendered in collapsible accordion components:\n\n```python\nclass Address(BaseModel):\n    street: str = \"123 Main St\"\n    city: str = \"Anytown\"\n    is_billing: bool = False\n\nclass User(BaseModel):\n    name: str\n    address: Address  # Rendered as collapsible accordion\n    backup_addresses: List[Address]  # List of accordions\n```\n\n**Key behaviors:**\n- Nested models inherit `disabled` and `spacing` settings from the parent form\n- Field prefixes are automatically managed (e.g., `user_address_street`)\n- Accordions are open by default for better user experience\n- Schema drift is handled gracefully - missing fields use defaults, unknown fields are ignored\n\n## Literal \u0026 Enum Fields\n\n`fh-pydantic-form` provides comprehensive support for choice-based fields through `Literal`, `Enum`, and `IntEnum` types, all automatically rendered as dropdown selects:\n\n### Literal Fields\n\n```python\nfrom typing import Literal, Optional\n\nclass OrderModel(BaseModel):\n    # Required Literal field - only defined choices available\n    shipping_method: Literal[\"STANDARD\", \"EXPRESS\", \"OVERNIGHT\"] = \"STANDARD\"\n    \n    # Optional Literal field - includes \"-- None --\" option\n    category: Optional[Literal[\"ELECTRONICS\", \"CLOTHING\", \"BOOKS\", \"OTHER\"]] = None\n```\n\n### Enum Fields\n\n```python\nfrom enum import Enum, IntEnum\n\nclass OrderStatus(Enum):\n    \"\"\"Order status enum with string values.\"\"\"\n    PENDING = \"pending\"\n    CONFIRMED = \"confirmed\" \n    SHIPPED = \"shipped\"\n    DELIVERED = \"delivered\"\n    CANCELLED = \"cancelled\"\n\nclass Priority(IntEnum):\n    \"\"\"Priority levels using IntEnum for numeric ordering.\"\"\"\n    LOW = 1\n    MEDIUM = 2\n    HIGH = 3\n    URGENT = 4\n\nclass OrderModel(BaseModel):\n    # Required Enum field with default\n    status: OrderStatus = OrderStatus.PENDING\n    \n    # Optional Enum field without default\n    payment_method: Optional[PaymentMethod] = None\n    \n    # Required IntEnum field with default\n    priority: Priority = Priority.MEDIUM\n    \n    # Optional IntEnum field without default\n    urgency_level: Optional[Priority] = Field(\n        None, description=\"Override priority for urgent orders\"\n    )\n    \n    # Enum field without default (required)\n    fulfillment_status: OrderStatus = Field(\n        ..., description=\"Current fulfillment status\"\n    )\n```\n\n### Field Rendering Behavior\n\n| Field Type | Required | Optional | Notes |\n|------------|----------|----------|-------|\n| **Literal** | Shows only defined choices | Includes \"-- None --\" option | String values displayed as-is |\n| **Enum** | Shows enum member values | Includes \"-- None --\" option | Displays `enum.value` in dropdown |\n| **IntEnum** | Shows integer values | Includes \"-- None --\" option | Maintains numeric ordering |\n\n**Key features:**\n- **Automatic dropdown generation** for all choice-based field types\n- **Proper value handling** - enum values are correctly parsed during form submission\n- **Optional field support** - includes None option when fields are Optional\n- **Field descriptions** become tooltips on hover\n- **Default value selection** - dropdowns pre-select the appropriate default value\n\n## Initial Values \u0026 Enum Parsing\n\n`fh-pydantic-form` intelligently parses initial values from dictionaries, properly converting strings and integers to their corresponding enum types:\n\n### Setting Initial Values\n\n```python\n# Example initial values from a dictionary\ninitial_values_dict = {\n    \"shipping_method\": \"EXPRESS\",      # Literal value as string\n    \"category\": \"ELECTRONICS\",         # Optional Literal value\n    \"status\": \"shipped\",               # Enum value (parsed to OrderStatus.SHIPPED)\n    \"payment_method\": \"paypal\",        # Optional Enum (parsed to PaymentMethod.PAYPAL)\n    \"priority\": 3,                     # IntEnum as integer (parsed to Priority.HIGH)\n    \"urgency_level\": 4,                # Optional IntEnum as integer (parsed to Priority.URGENT)\n    \"fulfillment_status\": \"confirmed\"  # Required Enum (parsed to OrderStatus.CONFIRMED)\n}\n\n# Create form with initial values\nform_renderer = PydanticForm(\"order_form\", OrderModel, initial_values=initial_values_dict)\n```\n\n### Parsing Behavior\n\nThe form automatically handles conversion between different value formats:\n\n| Input Type | Target Type | Example | Result |\n|------------|-------------|---------|--------|\n| String | Enum | `\"shipped\"` | `OrderStatus.SHIPPED` |\n| String | Optional[Enum] | `\"paypal\"` | `PaymentMethod.PAYPAL` |\n| Integer | IntEnum | `3` | `Priority.HIGH` |\n| Integer | Optional[IntEnum] | `4` | `Priority.URGENT` |\n| String | Literal | `\"EXPRESS\"` | `\"EXPRESS\"` (unchanged) |\n\n**Benefits:**\n- **Flexible data sources** - works with database records, API responses, or any dictionary\n- **Type safety** - ensures enum values are valid during parsing\n- **Graceful handling** - invalid enum values are passed through for Pydantic validation\n- **Consistent behavior** - same parsing logic for required and optional fields\n\n### Example Usage\n\n```python\n@rt(\"/\")\ndef get():\n    return mui.Form(\n        form_renderer.render_inputs(),  # Pre-populated with parsed enum values\n        fh.Div(\n            mui.Button(\"Submit\", type=\"submit\", cls=mui.ButtonT.primary),\n            form_renderer.refresh_button(\"🔄\"),\n            form_renderer.reset_button(\"↩️\"),  # Resets to initial parsed values\n            cls=\"mt-4 flex items-center gap-2\",\n        ),\n        hx_post=\"/submit_order\",\n        hx_target=\"#result\",\n        id=f\"{form_renderer.name}-form\",\n    )\n\n@rt(\"/submit_order\")\nasync def post_submit_order(req):\n    try:\n        # Validates and converts form data back to proper enum types\n        validated_order: OrderModel = await form_renderer.model_validate_request(req)\n        \n        # Access enum properties\n        print(f\"Status: {validated_order.status.value} ({validated_order.status.name})\")\n        print(f\"Priority: {validated_order.priority.value} ({validated_order.priority.name})\")\n        \n        return success_response(validated_order)\n    except ValidationError as e:\n        return error_response(e)\n```\n\nThis makes it easy to work with enum-based forms when loading data from databases, APIs, or configuration files.\n\n## Disabling \u0026 Excluding Fields\n\n### Disabling Fields\n\nYou can disable the entire form or specific fields:\n\n```python\n# Disable all fields\nform_renderer = PydanticForm(\"my_form\", FormModel, disabled=True)\n\n# Disable specific fields only\nform_renderer = PydanticForm(\n    \"my_form\",\n    FormModel,\n    disabled_fields=[\"field1\", \"field3\"]\n)\n```\n\n### Excluding Fields\n\nExclude specific fields from being rendered in the form:\n\n```python\nform_renderer = PydanticForm(\n    \"my_form\",\n    FormModel,\n    exclude_fields=[\"internal_field\", \"computed_field\"]\n)\n```\n\n**Important:** When fields are excluded from the UI, `fh-pydantic-form` automatically injects their default values during form parsing and validation. This ensures:\n\n- **Hidden fields with defaults** are still included in the final validated data\n- **Required fields without defaults** will still cause validation errors if not provided elsewhere\n- **Default factories** are executed to provide computed default values\n- **Nested BaseModel defaults** are converted to dictionaries for consistency\n\nThis automatic default injection means you can safely exclude fields that shouldn't be user-editable while maintaining data integrity.\n\n### SkipJsonSchema Fields\n\n`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.\n\n```python\nfrom pydantic.json_schema import SkipJsonSchema\n\nclass DocumentModel(BaseModel):\n    title: str\n    content: str\n    \n    # Hidden by default - system fields\n    document_id: SkipJsonSchema[str] = Field(\n        default_factory=lambda: f\"doc_{uuid4().hex[:12]}\",\n        description=\"Internal document ID\"\n    )\n    created_at: SkipJsonSchema[datetime.datetime] = Field(\n        default_factory=datetime.datetime.now,\n        description=\"Creation timestamp\"\n    )\n    version: SkipJsonSchema[int] = Field(\n        default=1, \n        description=\"Document version\"\n    )\n\n# Normal form - all SkipJsonSchema fields hidden\nform_normal = PydanticForm(\"doc_form\", DocumentModel)\n\n# Admin form - selectively show some SkipJsonSchema fields\nform_admin = PydanticForm(\n    \"admin_form\", \n    DocumentModel,\n    keep_skip_json_fields=[\n        \"document_id\",  # Show document ID\n        \"version\",      # Show version number\n        # created_at remains hidden\n    ]\n)\n```\n\n#### Nested SkipJsonSchema Fields\n\nThe feature supports dot notation for nested objects and list items:\n\n```python\nclass Address(BaseModel):\n    street: str\n    city: str\n    # Hidden system field\n    internal_id: SkipJsonSchema[str] = Field(default_factory=lambda: f\"addr_{uuid4().hex[:8]}\")\n\nclass UserModel(BaseModel):\n    name: str\n    main_address: Address\n    other_addresses: List[Address]\n\n# Show specific nested SkipJsonSchema fields\nform = PydanticForm(\n    \"user_form\",\n    UserModel,\n    keep_skip_json_fields=[\n        \"main_address.internal_id\",        # Show main address ID\n        \"other_addresses.internal_id\",     # Show all address IDs in the list\n    ]\n)\n```\n\n**Key Features:**\n- **Hidden by default:** SkipJsonSchema fields are automatically excluded from forms\n- **Selective visibility:** Use `keep_skip_json_fields` to show specific fields\n- **Nested support:** Access nested fields with dot notation (`\"main_address.internal_id\"`)\n- **List support:** Show fields in all list items (`\"addresses.internal_id\"`)\n- **Smart defaults:** Non-kept fields use model defaults, kept fields retain initial values\n- **Admin interfaces:** Perfect for admin panels or debugging where you need to see system fields\n\nSee `examples/complex_example.py` for a comprehensive demonstration of SkipJsonSchema field handling.\n\n## Refreshing \u0026 Resetting\n\nForms support dynamic refresh and reset functionality:\n\n```python\nmui.Form(\n    form_renderer.render_inputs(),\n    fh.Div(\n        mui.Button(\"Submit\", type=\"submit\", cls=mui.ButtonT.primary),\n        form_renderer.refresh_button(\"🔄 Refresh\"),  # Update display\n        form_renderer.reset_button(\"↩️ Reset\"),      # Restore initial values\n        cls=\"mt-4 flex items-center gap-2\",\n    ),\n    # ... rest of form setup\n)\n```\n\n- **Refresh button** updates the form display based on current values (useful for updating list item summaries)\n- **Reset button** restores all fields to their initial values with confirmation\n- Both use HTMX for seamless updates without page reloads\n\n**Dynamic forms via `template_name`:**\n- Refresh is routed through the template form and scoped to the specific instance via `fhpf_form_name`.\n- `reset_button()` becomes client-side (restores the initial HTML snapshot). Ensure `list_manipulation_js()` is included on the page.\n\n\n## Label Colors\n\nCustomize the appearance of field labels with the `label_colors` parameter:\n\n```python\nform_renderer = PydanticForm(\n    \"my_form\",\n    MyModel,\n    label_colors={\n        \"name\": \"text-blue-600\",    # Tailwind CSS class\n        \"score\": \"#E12D39\",        # Hex color value\n        \"status\": \"text-green-500\", # Another Tailwind class\n    },\n)\n```\n\n**Supported formats:**\n- **Tailwind CSS classes:** `\"text-blue-600\"`, `\"text-red-500\"`, etc.\n- **Hex color values:** `\"#FF0000\"`, `\"#0066CC\"`, etc.\n- **CSS color names:** `\"red\"`, `\"blue\"`, `\"darkgreen\"`, etc.\n\nThis 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. \n\n## Metrics \u0026 Highlighting\n\n`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.\n\n\u003cimg width=\"796\" alt=\"image\" src=\"https://github.com/user-attachments/assets/df2f8623-991d-45b1-80d8-5c7239187a74\" /\u003e\n\n\n### Basic Metrics Usage\n\n```python\nfrom fh_pydantic_form import PydanticForm\n\n# Define metrics for your form fields\nmetrics_dict = {\n    \"title\": {\n        \"metric\": 0.95,\n        \"comment\": \"Excellent title quality - clear and engaging\"\n    },\n    \"rating\": {\n        \"metric\": 0.3,\n        \"comment\": \"Low rating needs attention\"\n    },\n    \"status\": {\n        \"metric\": 0.0,\n        \"comment\": \"Critical status issue - requires immediate review\"\n    }\n}\n\n# Create form with metrics\nform_renderer = PydanticForm(\n    \"my_form\",\n    MyModel,\n    metrics_dict=metrics_dict\n)\n```\n\n### Metrics Dictionary Structure\n\nEach field can have the following metrics properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `metric` | `float` or `str` | Numeric score (0.0-1.0) or string assessment |\n| `color` | `str` | Custom color (overrides automatic color-coding) |\n| `comment` | `str` | Tooltip text shown on hover |\n\n### Automatic Color Coding\n\nNumeric metrics are automatically color-coded:\n\n- **1.0**: Bright green (perfect score)\n- **0.5-1.0**: Medium green (good range)\n- **0.0-0.5**: Dark red (needs attention)\n- **0.0**: Bright red (critical issue)\n\n```python\nmetrics_dict = {\n    \"field1\": {\"metric\": 1.0, \"comment\": \"Perfect!\"},      # Bright green\n    \"field2\": {\"metric\": 0.8, \"comment\": \"Very good\"},     # Medium green\n    \"field3\": {\"metric\": 0.3, \"comment\": \"Needs work\"},    # Dark red\n    \"field4\": {\"metric\": 0.0, \"comment\": \"Critical\"},      # Bright red\n}\n```\n\n### Custom Colors\n\nOverride automatic colors with custom values:\n\n```python\nmetrics_dict = {\n    \"status\": {\n        \"metric\": 0.0,\n        \"color\": \"purple\",  # Custom color overrides red\n        \"comment\": \"Status requires special attention\"\n    },\n    \"priority\": {\n        \"metric\": 1.0,\n        \"color\": \"#FF6B35\",  # Custom hex color\n        \"comment\": \"High priority with custom highlight\"\n    }\n}\n```\n\n### String Metrics\n\nUse string values for qualitative assessments:\n\n```python\nmetrics_dict = {\n    \"validation_status\": {\n        \"metric\": \"NEEDS_REVIEW\",\n        \"color\": \"#F59E0B\",  # Amber color\n        \"comment\": \"Requires human review\"\n    },\n    \"data_quality\": {\n        \"metric\": \"EXCELLENT\",\n        \"color\": \"#10B981\",  # Green color\n        \"comment\": \"Data quality exceeds standards\"\n    }\n}\n```\n\n### Nested Field Metrics\n\nSupport for nested objects and list items:\n\n```python\nmetrics_dict = {\n    # Nested object fields\n    \"author.name\": {\n        \"metric\": 0.95,\n        \"comment\": \"Author name perfectly formatted\"\n    },\n    \"author.email\": {\n        \"metric\": 0.9,\n        \"comment\": \"Email format excellent\"\n    },\n    \n    # List item metrics\n    \"tags[0]\": {\n        \"metric\": 1.0,\n        \"comment\": \"First tag is perfect\"\n    },\n    \"tags[1]\": {\n        \"metric\": 0.8,\n        \"comment\": \"Second tag very good\"\n    },\n    \n    # Complex nested paths\n    \"author.addresses[0].street\": {\n        \"metric\": 1.0,\n        \"comment\": \"Street address perfectly formatted\"\n    },\n    \"author.addresses[1].city\": {\n        \"metric\": 0.1,\n        \"color\": \"teal\",\n        \"comment\": \"City has verification problems\"\n    }\n}\n```\n\n### Practical Use Cases\n\n**LLM Structured Output Evaluation:**\n```python\n# Evaluate LLM extraction quality against ground truth\nextraction_metrics = {\n    \"product.name\": {\n        \"metric\": 0.9,\n        \"comment\": \"Name extracted with minor formatting issue: missing space\"\n    },\n    \"product.category\": {\n        \"metric\": 0.0,\n        \"comment\": \"Critical error: LLM misclassified Electronics instead of Sports\"\n    },\n    \"key_features\": {\n        \"metric\": 0.6,\n        \"comment\": \"LLM missed 2 of 5 key features from source text\"\n    },\n    \"extraction_confidence\": {\n        \"metric\": 1.0,\n        \"comment\": \"LLM confidence score accurately reflects actual performance\"\n    }\n}\n```\n\n**Document Processing Quality:**\n```python\n# Highlight extraction quality from documents\ndoc_extraction_metrics = {\n    \"invoice_number\": {\n        \"metric\": 1.0,\n        \"comment\": \"Invoice number perfectly extracted from PDF\"\n    },\n    \"line_items\": {\n        \"metric\": 0.75,\n        \"comment\": \"3/4 line items extracted correctly\"\n    },\n    \"total_amount\": {\n        \"metric\": 0.0,\n        \"comment\": \"Amount extraction failed - currency symbol confusion\"\n    }\n}\n```\n\nSee `examples/metrics_example.py` for a comprehensive demonstration of all metrics features.\n\n## ComparisonForm\n\nThe `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.\n\n\n\u003cimg width=\"1177\" alt=\"image\" src=\"https://github.com/user-attachments/assets/75020059-0d4d-4519-9c71-70a082d3242e\" /\u003e\n\n### Basic Usage\n\n```python\nfrom fh_pydantic_form import PydanticForm, ComparisonForm\n\n# Create two forms to compare\nleft_form = PydanticForm(\n    \"ground_truth\",\n    ProductModel,\n    initial_values=annotated_ground_truth,\n    disabled=False  # Editable for annotation correction\n)\n\nright_form = PydanticForm(\n    \"llm_output\", \n    ProductModel,\n    initial_values=llm_extracted_data,\n    disabled=True,  # Read-only LLM output\n    metrics_dict=extraction_quality_metrics\n)\n\n# Create comparison form\ncomparison_form = ComparisonForm(\n    name=\"extraction_evaluation\",\n    left_form=left_form,\n    right_form=right_form,\n    left_label=\"📝 Ground Truth (Editable)\",\n    right_label=\"🤖 LLM Output (with Quality Scores)\"\n)\n```\n\n### Required JavaScript\n\nInclude the comparison form JavaScript in your app headers:\n\n```python\nfrom fh_pydantic_form import comparison_form_js\n\napp, rt = fh.fast_app(\n    hdrs=[\n        mui.Theme.blue.headers(),\n        comparison_form_js(),  # Required for comparison forms\n    ],\n    pico=False,\n    live=True,\n)\n```\n\n### Complete Example\n\n```python\n@rt(\"/\")\ndef get():\n    return fh.Div(\n        mui.Container(\n            mui.Card(\n                mui.CardHeader(\n                    fh.H1(\"LLM Extraction Evaluation\")\n                ),\n                mui.CardBody(\n                    # Render the comparison form\n                    comparison_form.form_wrapper(\n                        fh.Div(\n                            comparison_form.render_inputs(),\n                            \n                            # Action buttons\n                            fh.Div(\n                                mui.Button(\n                                    \"Update Ground Truth\",\n                                    type=\"submit\",\n                                    hx_post=\"/update_ground_truth\",\n                                    hx_target=\"#result\"\n                                ),\n                                comparison_form.left_reset_button(\"Reset Left\"),\n                                comparison_form.left_refresh_button(\"Refresh Left\"),\n                                cls=\"mt-4 flex gap-2\"\n                            ),\n                            \n                            fh.Div(id=\"result\", cls=\"mt-4\")\n                        )\n                    )\n                )\n            )\n        )\n    )\n\n@rt(\"/update_ground_truth\")\nasync def post_update_ground_truth(req):\n    # Validate left form (ground truth side)\n    validated = await comparison_form.left_form.model_validate_request(req)\n    \n    # Process the ground truth update\n    return success_response(validated)\n\n# Register routes for both forms\ncomparison_form.register_routes(app)\n```\n\n### Key Features\n- **Aligned fields** input fields are horizontally aligned for easy comparison.\n- **Synchronized Accordions**: Expanding/collapsing sections syncs between both forms\n- **Independent Controls**: Separate refresh and reset buttons for each side\n- **Metrics Integration**: Right side typically shows LLM output quality scores\n- **Flexible Layout**: Responsive design works on desktop and mobile\n- **Form Validation**: Standard validation works with either form\n- **Intelligent List Copying**: Copy lists between forms with automatic length adjustment\n- **Multiple Comparisons per Page**: Copy + accordion sync is scoped to each comparison grid\n\n### Copying Between Forms\n\nThe 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:\n\n```python\n# Enable copy buttons (copy FROM right TO left)\ncomparison_form = ComparisonForm(\n    name=\"extraction_evaluation\",\n    left_form=left_form,\n    right_form=right_form,\n    left_label=\"Ground Truth\",\n    right_label=\"LLM Output\",\n    copy_left=True,  # Show copy buttons on right form to copy TO left\n)\n```\n\n**Copy Granularity Levels:**\n\nThe copy feature works at five different levels of granularity:\n\n1. **Individual Fields** - Copy a single field value (e.g., `name`, `price`, `status`)\n\n2. **Nested BaseModel (Entire Object)** - Copy all fields within a nested model at once\n\n3. **Individual Fields in Nested Models** - Copy a specific field within a nested object\n\n4. **Full List Fields** - Copy entire lists with automatic length adjustment\n\n5. **Individual List Items** - Add a single item from one list to another\n\n\n### Common Patterns\n\n**LLM Output Evaluation:**\n```python\n# Left: Editable ground truth\n# Right: Read-only LLM output with extraction quality metrics\ntruth_form = PydanticForm(..., disabled=False, metrics_dict={})\nllm_form = PydanticForm(..., disabled=True, metrics_dict=extraction_metrics)\n```\n\n**Document Extraction Comparison:**\n```python\n# Left: Manual annotation\n# Right: Automated LLM extraction\nmanual_form = PydanticForm(..., initial_values=manual_annotation)\nauto_form = PydanticForm(..., initial_values=llm_extraction, metrics_dict=quality_scores)\n```\n\n**Annotation Correction Workflow:**\n```python\n# Left: Correctable ground truth\n# Right: LLM output with confidence scores\nground_truth_form = PydanticForm(..., disabled=False)\nllm_output_form = PydanticForm(..., disabled=True, metrics_dict=confidence_scores)\n```\n\nSee `examples/comparison_example.py` for a complete LLM extraction evaluation interface demonstration.\n\n## Setting Initial Values\n\nYou can set initial form values of the form by passing a model instance or dictionary:\n\n```python\ninitial_data = MyModel(name=\"John\", tags=[\"happy\", \"joy\"])\nform_renderer = PydanticForm(\"my_form\", MyModel, initial_values=initial_data)\n\n\ninitial_data_dict = {\"name\": \"John\"} \nform_renderer = PydanticForm(\"my_form\", MyModel, initial_values=initial_values_dict)\n```\n\nThe 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.\n\n### Reusing Form Configuration with Different Values\n\nThe `with_initial_values()` method allows you to create a new form instance with the same configuration but different initial values:\n\n```python\n# Create a base form configuration\nbase_form = PydanticForm(\n    \"product_form\",\n    ProductModel,\n    disabled_fields=[\"id\"],\n    label_colors={\"name\": \"text-blue-600\", \"price\": \"text-green-600\"},\n    spacing=\"compact\"\n)\n\n# Create forms with different initial values using the same configuration\nform_for_product_a = base_form.with_initial_values({\"name\": \"Product A\", \"price\": 29.99})\nform_for_product_b = base_form.with_initial_values({\"name\": \"Product B\", \"price\": 45.50})\n\n# Or with model instances\nexisting_product = ProductModel(name=\"Existing Product\", price=19.99)\nform_for_existing = base_form.with_initial_values(existing_product)\n```\n\nThis is particularly useful for:\n- **Editing workflows** where you need the same form configuration for different records\n- **Template forms** where you want to reuse styling and field configurations\n- **Bulk operations** where you process multiple items with the same form structure\n\n\n\n### Schema Drift Resilience\n\n`fh-pydantic-form` gracefully handles model evolution and schema changes:\n\nInitial values can come from **older or newer** versions of your model – unknown fields are ignored gracefully and missing fields use defaults.\n\n```python\n# Your model evolves over time\nclass UserModel(BaseModel):\n    name: str\n    email: str           # Added in v2\n    phone: Optional[str] # Added in v3\n\n# Old data still works\nold_data = {\"name\": \"John\"}  # Missing newer fields\nform = PydanticForm(\"user\", UserModel, initial_values=old_data)\n\n# Newer data works too\nnew_data = {\"name\": \"Jane\", \"email\": \"jane@example.com\", \"phone\": \"555-1234\", \"removed_field\": \"ignored\"}\nform = PydanticForm(\"user\", UserModel, initial_values=new_data)\n```\n\n**Benefits:**\n- **Backward compatibility:** Old data structures continue to work\n- **Forward compatibility:** Unknown fields are silently ignored\n- **Graceful degradation:** Missing fields fall back to model defaults\n- **Production stability:** No crashes during rolling deployments\n\n## Custom Renderers\n\nThe library is extensible through custom field renderers for specialized input types:\n\n```python\nfrom fh_pydantic_form.field_renderers import BaseFieldRenderer\nfrom fh_pydantic_form import FieldRendererRegistry\n\nclass CustomDetail(BaseModel):\n    value: str = \"Default value\"\n    confidence: Literal[\"HIGH\", \"MEDIUM\", \"LOW\"] = \"MEDIUM\"\n\n    def __str__(self) -\u003e str:\n        return f\"{self.value} ({self.confidence})\"\n\nclass CustomDetailFieldRenderer(BaseFieldRenderer):\n    \"\"\"Display value input and dropdown side by side\"\"\"\n\n    def render_input(self):\n        value_input = fh.Div(\n            mui.Input(\n                value=self.value.get(\"value\", \"\"),\n                id=f\"{self.field_name}_value\",\n                name=f\"{self.field_name}_value\",\n                placeholder=f\"Enter {self.original_field_name.replace('_', ' ')} value\",\n                cls=\"uk-input w-full\",  \n            ),\n            cls=\"flex-grow\",\n        )\n\n        confidence_options = [\n            fh.Option(\n                opt, value=opt, selected=(opt == self.value.get(\"confidence\", \"MEDIUM\"))\n            )\n            for opt in [\"HIGH\", \"MEDIUM\", \"LOW\"]\n        ]\n\n        confidence_select = mui.Select(\n            *confidence_options,\n            id=f\"{self.field_name}_confidence\",\n            name=f\"{self.field_name}_confidence\",\n            cls_wrapper=\"w-[110px] min-w-[110px] flex-shrink-0\",\n        )\n\n        return fh.Div(\n            value_input,\n            confidence_select,\n            cls=\"flex items-start gap-2 w-full\",\n        )\n\n# Register the custom renderer (multiple ways)\nFieldRendererRegistry.register_type_renderer(CustomDetail, CustomDetailFieldRenderer)\n\n# Or pass directly to PydanticForm\nform_renderer = PydanticForm(\n    \"my_form\",\n    MyModel,\n    custom_renderers=[(CustomDetail, CustomDetailFieldRenderer)],\n)\n```\n\n### Registration Methods\n\n- **Type-based:** `register_type_renderer(CustomDetail, CustomDetailFieldRenderer)`\n- **Type name:** `register_type_name_renderer(\"CustomDetail\", CustomDetailFieldRenderer)`\n- **Predicate:** `register_type_renderer_with_predicate(lambda field: isinstance(field.annotation, CustomDetail), CustomDetailFieldRenderer)`\n\n## API Reference\n\n### PydanticForm Constructor\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `form_name` | `str` | Required | Unique identifier for the form (used for HTMX routes and prefixes) |\n| `model_class` | `Type[BaseModel]` | Required | The Pydantic model class to render |\n| `initial_values` | `Optional[Union[BaseModel, Dict]]` | `None` | Initial form values as model instance or dictionary |\n| `custom_renderers` | `Optional[List[Tuple[Type, Type[BaseFieldRenderer]]]]` | `None` | List of (type, renderer_class) pairs for custom rendering |\n| `disabled` | `bool` | `False` | Whether to disable all form inputs |\n| `disabled_fields` | `Optional[List[str]]` | `None` | List of specific field names to disable |\n| `label_colors` | `Optional[Dict[str, str]]` | `None` | Mapping of field names to CSS colors or Tailwind classes |\n| `exclude_fields` | `Optional[List[str]]` | `None` | List of field names to exclude from rendering (auto-injected on submission) |\n| `keep_skip_json_fields` | `Optional[List[str]]` | `None` | List of SkipJsonSchema field paths to selectively show (supports dot notation for nested fields) |\n| `spacing` | `SpacingValue` | `\"normal\"` | Spacing theme: `\"normal\"`, `\"compact\"`, or `SpacingTheme` enum |\n| `metrics_dict` | `Optional[Dict[str, Dict]]` | `None` | Field metrics for highlighting and tooltips |\n| `template_name` | `Optional[str]` | `None` | Route name to use for list/refresh/reset actions (useful for dynamic forms with shared template routes) |\n\n### ComparisonForm Constructor\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `name` | `str` | Required | Unique identifier for the comparison form |\n| `left_form` | `PydanticForm` | Required | Form to display on the left side |\n| `right_form` | `PydanticForm` | Required | Form to display on the right side |\n| `left_label` | `str` | `\"Left\"` | Label for the left form |\n| `right_label` | `str` | `\"Right\"` | Label for the right form |\n\n### PydanticForm Methods\n\n| Method | Purpose |\n|--------|---------|\n| `render_inputs()` | Generate the HTML form inputs (without `\u003cform\u003e` wrapper) |\n| `with_initial_values(initial_values, metrics_dict=None)` | Create a new form instance with same configuration but different initial values |\n| `refresh_button(text=None, **kwargs)` | Create a refresh button component |\n| `reset_button(text=None, **kwargs)` | Create a reset button component |\n| `register_routes(app)` | Register HTMX endpoints for list manipulation |\n| `parse(form_dict)` | Parse raw form data into model-compatible dictionary |\n| `model_validate_request(req)` | Extract, parse, and validate form data from request |\n\n### ComparisonForm Methods\n\n| Method | Purpose |\n|--------|---------|\n| `render_inputs()` | Generate side-by-side form inputs |\n| `form_wrapper(content)` | Wrap content with comparison form structure |\n| `left_reset_button(text=None, **kwargs)` | Reset button for left form |\n| `right_reset_button(text=None, **kwargs)` | Reset button for right form |\n| `left_refresh_button(text=None, **kwargs)` | Refresh button for left form |\n| `right_refresh_button(text=None, **kwargs)` | Refresh button for right form |\n| `register_routes(app)` | Register HTMX endpoints for both forms |\n\n### Utility Functions\n\n| Function | Purpose |\n|----------|---------|\n| `list_manipulation_js()` | JavaScript for list reordering and toggle functionality |\n| `comparison_form_js()` | JavaScript for comparison form accordion synchronization |\n| `default_dict_for_model(model_class)` | Generate default values for all fields in a model |\n| `default_for_annotation(annotation)` | Get sensible default for a type annotation |\n\n## Contributing\n\nContributions are welcome! Please feel free to open an issue or submit a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcura%2Ffh-pydantic-form","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcura%2Ffh-pydantic-form","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcura%2Ffh-pydantic-form/lists"}