Clarify Plugin

Structured clarification forms with preference memory for human-in-the-loop agent operations.

Overview

The Clarify plugin enables agents to ask users clarifying questions during execution. It provides a tiered feature set:

| Tier | Features | |------|----------| | Community | Basic clarification protocol, soft upgrade prompt | | Team | Structured forms (radio, checkbox, text) + preference memory | | Enterprise | Rich forms (all controls) + preference memory |

Architecture

The basic clarification protocol (models and core functions) lives in core/clarification/. This plugin extends it with:

• Structured Forms: Generate forms with various control types based on context
• Preference Memory: Remember user preferences using semantic matching
• CrewAI Integration: ask_user tool for agent use
• State Conflict Resolution: Help users resolve conflicting state values

Usage

Basic Clarification (Core)

from core.clarification import request_clarification, ClarificationResponse

Async context
response = await request_clarification(
    conversation_id="conv_123",
    question="Which environment should I deploy to?",
    options=["staging", "production"],
    timeout=300.0  # 5 minutes
)

CrewAI Tool (Plugin)

from plugins.clarify.protocol import create_ask_user_tool

ask_user = create_ask_user_tool()
In agent tools list
agent = Agent(
    role="Deployer",
    tools=[ask_user],
    ...
)

Synchronous Marker (Plugin)

For non-async contexts, use markers that the orchestrator intercepts:

from plugins.clarify.protocol import request_clarification_sync

Returns a marker string
marker = request_clarification_sync("Which layer?", ["LA", "PA", "SA"])
Result: "CLARIFY:Which layer?:LA|PA|SA"

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/clarify/form/generate | POST | Generate structured form | | /api/clarify/form/submit | POST | Submit form response | | /api/clarify/preferences | GET/POST | Manage saved preferences | | /api/clarify/upgrade-prompt | GET | Get upgrade prompt for community tier |

Configuration

The plugin auto-detects the license tier from core.config.get_settings().tier.

Testing

pytest plugins/clarify/tests/ -v

Files

plugins/clarify/
├── __init__.py          # Package exports
├── plugin.py            # Plugin class
├── protocol.py          # Clarification protocol extensions
├── routes.py            # FastAPI routes
├── models.py            # Database models
├── forms/               # Form generation
├── preferences/         # Preference memory
├── ui/                  # Frontend components
└── tests/               # Plugin tests