src/builtin_docs.py

"""
Embedded LLM documentation for form generation. Used directly in prompts — no URL or file read.
Same shape as /api/docs/form-schema so context_pack_builder works unchanged.
"""

BUILTIN_DOCS = {
    "version": "1.0.0",
    "lastUpdated": "2025-01-01T00:00:00Z",
    "formSchema": {
        "structure": "title (string), description? (string), fields (array of field objects)",
        "requiredFields": ["title", "fields"],
        "optionalFields": ["description"],
        "example": {
            "title": "Example Form",
            "description": "Optional",
            "fields": [
                {"id": "field-1", "type": "text", "label": "Label", "required": True, "placeholder": "..."}
            ],
        },
    },
    "fieldTypes": {
        "text": {"description": "Single-line text input.", "requiredProperties": ["id", "type", "label"]},
        "textarea": {"description": "Multi-line text.", "requiredProperties": ["id", "type", "label"]},
        "email": {"description": "Email with validation.", "requiredProperties": ["id", "type", "label"]},
        "tel": {"description": "Phone number.", "requiredProperties": ["id", "type", "label"]},
        "number": {"description": "Numeric input.", "requiredProperties": ["id", "type", "label"]},
        "select": {"description": "Dropdown; use options array.", "requiredProperties": ["id", "type", "label"]},
        "radio": {"description": "Single choice; use options.", "requiredProperties": ["id", "type", "label"]},
        "checkbox": {"description": "Checkboxes; use options.", "requiredProperties": ["id", "type", "label"]},
        "file": {"description": "File upload.", "requiredProperties": ["id", "type", "label"]},
        "date": {"description": "Date picker.", "requiredProperties": ["id", "type", "label"]},
        "rating": {"description": "Star or scale rating; settings.rating.max.", "requiredProperties": ["id", "type", "label"]},
        "nps": {"description": "NPS 0-10; settings.nps.minLabel/maxLabel.", "requiredProperties": ["id", "type", "label"]},
        "text-block": {"description": "Static text/content.", "requiredProperties": ["id", "type", "label"]},
        "document-extraction": {"description": "AI document extraction; requires settings.documentExtraction.customFields.", "requiredProperties": ["id", "type", "label"]},
        "matrix": {"description": "Matrix/grid; settings.matrix rowLabels, columnLabels.", "requiredProperties": ["id", "type", "label"]},
        "likert": {"description": "Likert scale.", "requiredProperties": ["id", "type", "label"]},
        "ranking": {"description": "Ranking of options.", "requiredProperties": ["id", "type", "label"]},
        "toggle": {"description": "Yes/No toggle.", "requiredProperties": ["id", "type", "label"]},
        "name": {"description": "Structured name; settings.name.", "requiredProperties": ["id", "type", "label"]},
        "address": {"description": "Address fields.", "requiredProperties": ["id", "type", "label"]},
        "datetime": {"description": "Date and time.", "requiredProperties": ["id", "type", "label"]},
    },
    "conditionalLogic": {
        "overview": "Show, hide, or validate fields based on other fields. Use conditionalLogic: { enabled: true, action: 'show'|'hide', operator: 'AND'|'OR', conditions: [{ fieldId, operator, value? }] }.",
        "operators": {
            "equals": {"description": "Value equals (case-insensitive for text)."},
            "not_equals": {"description": "Value does not match."},
            "contains": {"description": "Value contains substring; for checkbox, value in selected array."},
            "not_contains": {"description": "Value does not contain."},
            "starts_with": {"description": "Starts with string."},
            "ends_with": {"description": "Ends with string."},
            "greater_than": {"description": "Numeric/date greater than."},
            "less_than": {"description": "Numeric/date less than."},
            "between": {"description": "Between two values; use value and secondValue."},
            "is_empty": {"description": "Field is empty; no value needed."},
            "is_not_empty": {"description": "Field has value; no value needed."},
            "matches_pattern": {"description": "Regex; use pattern key."},
        },
        "actions": {
            "show": {"example": {"enabled": True, "action": "show", "operator": "AND", "conditions": [{"fieldId": "x", "operator": "equals", "value": "y"}]}},
            "hide": {"example": {"enabled": True, "action": "hide", "operator": "OR", "conditions": [{"fieldId": "x", "operator": "equals", "value": "y"}]}},
            "validate": {"example": {"enabled": True, "action": "validate", "operator": "AND", "conditions": [], "validationMessage": "Optional message"}},
        },
        "examples": [
            {"title": "Show when", "json": {"enabled": True, "action": "show", "operator": "AND", "conditions": [{"fieldId": "account-type", "operator": "equals", "value": "Business"}]}},
        ],
    },
    "aiFields": {
        "documentExtraction": {
            "description": "AI-powered field that extracts structured data from uploaded documents (PDF/images). Requires settings.documentExtraction with customFields, acceptedFileTypes, maxFileSize, and verificationPrompt (descriptive text: how to verify the candidate against extracted data; for job forms use role/must-have requirements — never put only a number like 80).",
            "configuration": {
                "customFields": {
                    "description": "Array of { id, name, description, fieldType, required, editable }. fieldType: single_value | list | number | date.",
                    "fieldTypes": {"single_value": {}, "list": {}, "number": {}, "date": {}},
                },
                "acceptedFileTypes": "Array of allowed extensions, e.g. ['pdf','doc','docx','png','jpg','jpeg'].",
                "maxFileSize": "Max file size in bytes (e.g. 10485760 for 10MB).",
                "verificationPrompt": "Descriptive text only: how to verify the candidate (e.g. experience, degree, skills). Never put only a number; use full sentences.",
            },
            "exampleConfigurations": [
                {
                    "useCase": "Resume",
                    "json": {
                        "id": "resume-upload",
                        "type": "document-extraction",
                        "label": "Upload Resume",
                        "required": True,
                        "settings": {
                            "documentExtraction": {
                                "customFields": [
                                    {"id": "fullName", "name": "Full Name", "description": "Candidate full name", "fieldType": "single_value", "required": True, "editable": True},
                                    {"id": "email", "name": "Email", "description": "Email address", "fieldType": "single_value", "required": True, "editable": True},
                                    {"id": "phone", "name": "Phone", "description": "Phone number", "fieldType": "single_value", "required": False, "editable": True},
                                    {"id": "experience", "name": "Work Experience", "description": "Job titles, companies, dates", "fieldType": "list", "required": True, "editable": True},
                                    {"id": "education", "name": "Education", "description": "Degrees, institutions, dates", "fieldType": "list", "required": False, "editable": True},
                                    {"id": "skills", "name": "Skills", "description": "Skills or technologies", "fieldType": "list", "required": False, "editable": True},
                                    {"id": "yearsExperience", "name": "Years of Experience", "description": "Total years", "fieldType": "number", "required": False, "editable": True},
                                ],
                                "acceptedFileTypes": ["pdf", "doc", "docx", "png", "jpg", "jpeg"],
                                "maxFileSize": 10485760,
                                "verificationPrompt": "Candidate must have at least 2 years of experience, a relevant degree (e.g. masters in CS or related field), and skills matching the role (e.g. LangGraph or similar frameworks).",
                            }
                        },
                    },
                },
            ],
        },
    },
    "exampleForms": [
        {"title": "Contact", "json": {"title": "Contact", "fields": [{"id": "name", "type": "text", "label": "Name", "required": True}, {"id": "email", "type": "email", "label": "Email", "required": True}, {"id": "message", "type": "textarea", "label": "Message", "required": True}]}, "featuresUsed": ["text", "email", "textarea"]},
        {"title": "Job with resume", "json": {"title": "Job Application", "fields": [{"id": "resume-upload", "type": "document-extraction", "label": "Upload Resume", "required": True, "settings": {"documentExtraction": {"customFields": [{"id": "fullName", "name": "Full Name", "description": "Candidate full name", "fieldType": "single_value", "required": True, "editable": True}, {"id": "email", "name": "Email", "description": "Email address", "fieldType": "single_value", "required": True, "editable": True}, {"id": "experience", "name": "Work Experience", "description": "Job titles and companies", "fieldType": "list", "required": True, "editable": True}], "acceptedFileTypes": ["pdf", "doc", "docx", "png", "jpg", "jpeg"], "maxFileSize": 10485760, "verificationPrompt": "Candidate must meet role requirements: required years of experience, degree, and key skills as specified for the role."}}}]}, "featuresUsed": ["document-extraction"]},
    ],
    "bestPractices": [
        "Use kebab-case for field ids. Use appropriate field types.",
        "Add conditionalLogic when fields should show/hide based on others.",
        "For document-extraction, define customFields with clear descriptions.",
        "Use validation (minLength, maxLength, etc.) where appropriate.",
    ],
}