KirokuForms Use Cases

/* HTML: Ultra-fast lead capture form (HTML-only option) */
/* Apply your brand's look and feel with 'your-brand-styles' class */
/* KirokuForms CSS variables allow deep theme customization. */
<form
  action="https://www.kirokuforms.com/f/your-marketing-campaign-slug"
  method="POST"
  class="your-brand-styles kiroku-embed-form"
>
  <div class="form-field-group">
    <label for="mk-email">Work Email:</label>
    <input type="email" id="mk-email" name="email" placeholder="Enter your work email" required>
  </div>

  <div class="form-field-group">
    <label for="mk-company">Company Name:</label>
    <input type="text" id="mk-company" name="company" placeholder="Company name (optional)">
  </div>

  <button type="submit" class="your-cta-button">Get Free Demo</button>
</form>

/* Optional JavaScript Enhancement: Ultra-lightweight at 7.8KB */
/* Smaller than most favicon files! Compare: jQuery alone is ~30KB */
<script src="https://www.kirokuforms.com/js/kiroku-form.js" defer></script>
/* Adds AJAX submission, client-side validation, no-redirect UX */

/* JSON: Advanced Lead Routing & Automation Rules in KirokuForms */
/* These rules are configured in your KirokuForms settings for a specific form. */
{
  "form_id": "product-demo-request-advanced",
  "automation_rules": [
    {
      "rule_name": "Route Enterprise Leads to Sales",
      "condition": {
        "field": "company_size",
        "operator": "greater_than_or_equal_to",
        "value": "500"
      },
      "actions": [
        {"type": "webhook", "target_url": "https://salesforce.com/api/enterprise-leads"},
        {"type": "email_notification", "recipient": "enterprise-sales-team@example.com"},
        {"type": "add_tag", "tag_name": "EnterpriseProspect"}
      ]
    },
    {
      "rule_name": "Nurture SMB Leads via Email Sequence",
      "condition": {
        "field": "company_size",
        "operator": "less_than",
        "value": "500"
      },
      "actions": [
        {"type": "add_to_mailchimp_list", "list_id": "YOUR_SMB_NURTURE_LIST_ID"},
        {"type": "add_tag", "tag_name": "SMBProspect"}
      ]
    }
  ]
}

/* JS Embed: Easiest way to get a themed KirokuForm on your site */
/* Just pick a form slug and a theme - our 7.8KB script handles the rest */
<div
  data-kiroku-form="smallbiz-contact-form-main"
  data-theme="professional-blue"
  data-success-message="Thanks for reaching out! We'll reply within 24 hours."
>
  </div>
<script src="https://www.kirokuforms.com/js/kiroku-form.js" defer></script>
/* Total overhead: Just 7.8KB - smaller than most images! */

/* HTML-Only Alternative: For maximum speed & simple integration */
<form
  action="https://www.kirokuforms.com/f/smallbiz-contact-form-main"
  method="POST"
  class="kiroku-embed-form your-website-styles"
>
  <div class="form-row">
    <label for="sb-name">Your Name:</label>
    <input type="text" id="sb-name" name="name" placeholder="Your name" required>
  </div>
  <div class="form-row">
    <label for="sb-email">Email Address:</label>
    <input type="email" id="sb-email" name="email" placeholder="Email address" required>
  </div>
  <div class="form-row">
    <label for="sb-message">How can we help?</label>
    <textarea id="sb-message" name="message" placeholder="Tell us about your needs..." rows="4"></textarea>
  </div>
  <button type="submit">Send Message</button>
</form>

/* Conceptual Overview: Managing Multiple Form Types in KirokuForms */
/* In your KirokuForms Dashboard, you can create and manage various forms, such as: */

/* 1. Contact & Inquiry Forms */
/* 2. Customer Feedback Forms */
/* 3. Service Booking Forms */
/* 4. Support Ticket Forms */

/* Example JSON structure for defining a versatile contact form: */
{
  "form_config": {
    "slug": "general-contact-sb",
    "name": "General Contact Form (Small Business)",
    "theme_id": "clean-light",
    "fields": [
      {"type": "text", "name": "full_name", "label": "Full Name", "required": true},
      {"type": "email", "name": "contact_email", "label": "Email Address", "required": true},
      {"type": "select", "name": "inquiry_type", "label": "How can we help?", "options": [
        {"label": "General Question", "value": "general"},
        {"label": "Service Inquiry", "value": "service"},
        {"label": "Support Request", "value": "support"},
        {"label": "Feedback", "value": "feedback"}
      ]},
      {"type": "textarea", "name": "inquiry_message", "label": "Your Message", "rows": 5}
    ],
    "settings": {
      "email_notifications": ["your-email@smallbusiness.com"],
      "success_message": "Thanks for your message! We'll be in touch soon.",
      "submit_button_text": "Send Inquiry"
    }
  }
}

/* HTML: Zero-JavaScript, maximum performance form */
/* Ideal for static sites, JAMstack, Astro, Eleventy, etc. */
/* This form POSTs directly to KirokuForms. Style with your own CSS. */
<form
  action="https://www.kirokuforms.com/f/your-developer-newsletter-signup"
  method="POST"
  class="kiroku-embed-form your-custom-styles"
  id="dev-newsletter-form"
>
  <div class="form-element">
    <label for="dev-email">Email:</label>
    <input type="email" id="dev-email" name="email" placeholder="you@example.dev" required>
  </div>
  <input type="hidden" name="source" value="dev-landing-page-html-form">
  <button type="submit">Subscribe</button>
</form>

/* Optional JavaScript Enhancement: Ultra-lightweight at 7.8KB */
/* Compare: jQuery (30KB), React (40KB+), Vue (35KB+) */
/* Our script adds AJAX submission, validation, no-redirect UX */
<script src="https://www.kirokuforms.com/js/kiroku-form.js" defer></script>

/* Progressive Enhancement Example (manual approach) */
<script>
  const formElement = document.getElementById('dev-newsletter-form');
  if (formElement && 'fetch' in window) {
    formElement.addEventListener('submit', async (event) => {
      event.preventDefault();
      const formData = new FormData(formElement);

      // Show loading state
      const submitButton = formElement.querySelector('button[type="submit"]');
      if (submitButton) {
        submitButton.disabled = true;
        submitButton.textContent = 'Submitting...';
      }

      try {
        const response = await fetch(formElement.action, {
          method: 'POST',
          body: formData
        });

        if (response.ok) {
          // Handle success
          alert('Subscribed successfully!');
          formElement.reset();
        } else {
          throw new Error('Submission failed');
        }
      } catch (error) {
        alert('Error: ' + error.message);
      } finally {
        if (submitButton) {
          submitButton.disabled = false;
          submitButton.textContent = 'Subscribe';
        }
      }
    });
  }
</script>

/* JavaScript: Example using Fetch API to interact with KirokuForms API */

/* Function to create a new form programmatically */
async function createKirokuFormViaAPI() {
  const apiEndpoint = 'https://api.kirokuforms.com/v1/forms';
  const apiKey = 'YOUR_DEVELOPER_API_KEY';

  const formPayload = {
    name: 'Dev Project Beta Signup Form V2',
    slug: 'dev-beta-signup-v2',
    fields: [
      {
        type: 'email',
        name: 'email',
        label: 'Your Email',
        required: true,
        placeholder: 'dev@example.com'
      },
      {
        type: 'text',
        name: 'github_username',
        label: 'GitHub Username (Optional)'
      },
      {
        type: 'select',
        name: 'interest_area',
        label: 'Primary Interest',
        options: [
          { label: 'Frontend Frameworks', value: 'frontend' },
          { label: 'Backend APIs', value: 'backend' },
          { label: 'DevOps & Tooling', value: 'devops' }
        ],
        required: true
      }
    ],
    settings: {
      success_message: 'Thanks for signing up for the beta! We will be in touch.',
      theme_id: 'dark_developer_theme',
      enable_spam_protection: true,
      // Webhook for real-time integration
      webhooks: [{
        url: 'https://api.yourapp.com/beta-signups',
        events: ['form.submitted'],
        headers: {
          'Authorization': 'Bearer YOUR_WEBHOOK_SECRET'
        }
      }]
    }
  };

  try {
    const response = await fetch(apiEndpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(formPayload)
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({
        message: response.statusText
      }));
      throw new Error(`API Error (${response.status}): ${errorData.message}`);
    }

    const newForm = await response.json();
    console.log('Created form:', newForm.data);

    // Return both ID and embed code for immediate use
    return {
      formId: newForm.data.id,
      embedCode: `<div data-kiroku-form="${newForm.data.slug}"></div>
<script src="https://www.kirokuforms.com/js/kiroku-form.js" defer></script>`,
      htmlAction: `https://www.kirokuforms.com/f/${newForm.data.slug}`
    };
  } catch (error) {
    console.error('KirokuForms API interaction failed:', error);
    throw error;
  }
}

/* Example: Fetch submissions with filtering */
async function getFormSubmissions(formId, filters = {}) {
  const apiKey = 'YOUR_DEVELOPER_API_KEY'; // Ensure apiKey is defined in this scope or passed
  const url = new URL(`https://api.kirokuforms.com/v1/forms/${formId}/submissions`);

  // Add query parameters for filtering
  Object.entries(filters).forEach(([key, value]) => {
    url.searchParams.append(key, String(value)); // Ensure value is string
  });

  const response = await fetch(url.toString(), { // Use url.toString()
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  if (response.ok) {
    const data = await response.json();
    return data.submissions; // Assuming the API returns { submissions: [...] }
  }
  const errorData = await response.json().catch(() => ({ message: response.statusText }));
  throw new Error(`Failed to fetch submissions: ${errorData.message}`);
}

/* Usage Example */
// createKirokuFormViaAPI()
//   .then(result => {
//     console.log('Form created:', result.formId);
//     console.log('Embed this:', result.embedCode);
//   })
//   .catch(error => console.error('Error:', error));

# Python: KirokuForms Python SDK for seamless HITL integration
# Install with: pip install kirokuforms

from kirokuforms import KirokuFormsHITL

# Initialize HITL client with your KirokuForms API key
hitl_client = KirokuFormsHITL(
    api_key="YOUR_KIROKU_AI_API_KEY",
    base_url="https://kirokuforms.com/api/mcp" # Or your self-hosted endpoint
)

# Example: AI generated text that needs human review for safety and accuracy
ai_generated_summary = """
KirokuForms is a powerful tool for AI developers to easily integrate
human feedback loops using Python and LangGraph.
"""

# Define the review task payload - dynamically create the review form
task_payload = {
    "title": "Review AI-Generated Content Summary",
    "description": "Please verify the AI-generated summary for factual accuracy, tone, and safety.",
    "fields": [
        {
            "type": "textarea",
            "name": "original_text_display",
            "label": "Original AI Output (Read-Only):",
            "defaultValue": ai_generated_summary,
            "readOnly": True # Corrected to Python boolean
        },
        {
            "type": "radio",
            "name": "accuracy_rating",
            "label": "Accuracy Rating:",
            "required": True, # Corrected to Python boolean
            "options": [
                {"label": "Highly Accurate", "value": "high"},
                {"label": "Mostly Accurate", "value": "medium"},
                {"label": "Needs Significant Correction", "value": "low"}
            ]
        },
        {
            "type": "checkbox",
            "name": "issues_identified",
            "label": "Specific Issues (if any):",
            "options": [
                {"label": "Factual Error", "value": "factual_error"},
                {"label": "Awkward Phrasing", "value": "phrasing"},
                {"label": "Tone is Off", "value": "tone"},
                {"label": "Potentially Harmful", "value": "harmful_content"}
            ]
        },
        {
            "type": "textarea",
            "name": "reviewer_suggestions",
            "label": "Suggestions for Improvement / Corrected Text:",
            "placeholder": "Please provide your detailed feedback or the corrected version here..."
        }
    ],
    "metadata": {
        "ai_model_version": "claude-3-opus-20240229",
        "source_document_url": "https://example.com/original-article",
        "priority": "high"
    },
    "task_id": "content-review-task-007"  # Your custom tracking ID
}

try:
    # Submit task to KirokuForms HITL platform
    task_response = hitl_client.create_task(**task_payload)

    task_id_from_response = task_response.get('taskId') # Renamed to avoid conflict
    review_url = task_response.get('formUrl')

    print(f"HITL Task created: {task_id_from_response}")
    print(f"Human Review URL: {review_url}")
    print("Email notification sent to assigned reviewers (if configured)")

    # Option 1: Wait for completion (blocking)
    # print("Waiting for human review completion...")
    # result = hitl_client.get_task_result(task_id_from_response, wait=True, timeout=600)

    # Option 2: Use webhooks for async notification (recommended)
    # Configure webhook in your KirokuForms settings:
    # POST to your endpoint when task completes

    # Option 3: Poll for results
    print("Use webhooks or polling to get results when complete")

    # Example result structure you might receive via webhook or polling:
    # {
    #   'taskId': 'content-review-task-007',
    #   'status': 'completed',
    #   'submissionData': {
    #     'accuracy_rating': 'high',
    #     'issues_identified': ['phrasing'],
    #     'reviewer_suggestions': 'Consider changing "powerful tool" to "comprehensive platform"'
    #   },
    #   'reviewer_id': 'reviewer_123', # If available
    #   'completion_time': '2024-01-15T10:30:00Z'
    # }

except Exception as e:
    print(f"HITL Task creation failed: {e}")

# Python: LangGraph integration with KirokuForms Human Checkpoints
# Install: pip install langgraph kirokuforms-langgraph

from langgraph.graph import StateGraph, END
from kirokuforms_langgraph import KirokuFormsCheckpoint # Ensure this import path is correct
from typing import TypedDict, Annotated, List, Optional

# 1. Define your agent's state
class AgentState(TypedDict):
    input_query: str
    generated_plan: Optional[List[str]]
    # This will be populated by KirokuFormsCheckpoint
    human_review_data: Annotated[Optional[dict], lambda x: x.get("human_review_data") if isinstance(x, dict) else None]
    final_decision: Optional[str]

# 2. Define your LangGraph nodes (AI logic)
def planning_node(state: AgentState):
    """AI generates a plan that needs human review"""
    print(f"AI Planning for query: '{state['input_query']}'")

    # Your LLM call here - simulated for example
    generated_plan = [
        "Step 1: Understand user requirements for the KirokuForms demo",
        "Step 2: Prepare key talking points about HTML-only forms and API",
        "Step 3: Identify a complex use case for the AI HITL feature",
        "Step 4: Schedule demo and send pre-demo questionnaire form"
    ]

    return {"generated_plan": generated_plan}

def execution_node(state: AgentState):
    """Execute the plan after human approval"""
    review_data = state.get('human_review_data', {})
    verdict = review_data.get('plan_verdict', 'N/A') # Default if not found
    comments = review_data.get('reviewer_comments', '')

    print(f"Executing plan with human verdict: {verdict}")
    if comments:
        print(f"Human feedback: {comments}")

    return {"final_decision": f"Plan executed with {verdict} approval"}

# 3. Create KirokuForms Checkpoint for human review
human_plan_review = KirokuFormsCheckpoint(
    # Define the review form dynamically
    form_definition={
        "title": "Human Review: AI Agent's Proposed Plan",
        "description": "Please review the AI-generated plan and provide your feedback.",
        "fields": [
            {
                "type": "textarea",
                "name": "display_ai_plan",
                "label": "AI Generated Plan (Read-Only):",
                "default_value_key": "generated_plan",  # Auto-populate from state
                "read_only": True, # Python boolean
                "rows": 6
            },
            {
                "type": "radio",
                "name": "plan_verdict",
                "label": "Your Decision:",
                "required": True, # Python boolean
                "options": [
                    {"label": "Approve Plan - Proceed to Execution", "value": "approve"},
                    {"label": "Reject Plan - Requires Re-planning", "value": "reject"},
                    {"label": "Modify Plan - See comments below", "value": "modify"}
                ]
            },
            {
                "type": "textarea",
                "name": "reviewer_comments",
                "label": "Comments / Modifications:",
                "placeholder": "If rejecting or modifying, please provide specific details...",
                "rows": 4
            }
        ]
    },
    # Alternative: Use pre-configured template from KirokuForms dashboard
    # form_template_id="your-agent-plan-review-template-slug",

    kiroku_api_key="YOUR_KIROKU_AI_API_KEY", # Ensure this is securely managed
    output_key="human_review_data",  # Where to store form submission in state

    # Optional: Configure notifications and assignment
    reviewer_config={
        "notify_emails": ["reviewer@example.com"], # Use actual emails
        "timeout_minutes": 60, # Agent waits up to 60 mins for review
        "priority": "high"
    }
)

# 4. Build the LangGraph with human checkpoint
graph_builder = StateGraph(AgentState)

# Add nodes
graph_builder.add_node("planner", planning_node)
graph_builder.add_node("human_review", human_plan_review)  # KirokuForms checkpoint
graph_builder.add_node("executor", execution_node)

# Set entry point and edges
graph_builder.set_entry_point("planner")
graph_builder.add_edge("planner", "human_review")

# Conditional routing based on human feedback
def decide_after_review(state: AgentState):
    """Route based on human review decision"""
    review_data = state.get("human_review_data", {})
    verdict = review_data.get("plan_verdict")

    print(f"Human decision from review: {verdict}")

    if verdict == 'approve':
        return "executor"
    elif verdict == 'reject':
        # In a real scenario, you might loop back to 'planner' or an error state
        print("Plan Rejected by Human. Ending workflow.")
        return END
    elif verdict == 'modify':
        # For simplicity, proceeding to executor. A real flow might re-plan or apply modifications.
        print("Plan to be executed with modifications noted.")
        return "executor"
    else:
        print("No clear decision from human review. Ending workflow.")
        return END

graph_builder.add_conditional_edges(
    "human_review",
    decide_after_review,
    {
        "executor": "executor",
        END: END
    }
)
graph_builder.add_edge("executor", END)

# 5. Compile the agent
compiled_agent = graph_builder.compile()

# Example execution (conceptual, as it involves external service calls)
# initial_state = {
#     "input_query": "Plan a comprehensive KirokuForms product demo for an enterprise client"
# }

# print("Starting AI agent with human checkpoints...")
# print("Agent will pause for human review automatically if KirokuFormsCheckpoint is invoked.")

# To run and see the flow (replace with actual streaming/invocation):
# for event in compiled_agent.stream(initial_state, stream_mode="values"):
#     print(f"Workflow Event: {list(event.keys())[0]} - State: {event[list(event.keys())[0]]}")
#     # The stream will pause at human_review until the form is submitted in KirokuForms