> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Options Architecture

> Reference for the Kodexa Options system architecture, including how declarative options enable flexible, type-safe configuration interfaces across components.

The Options system is a foundational feature in Kodexa that enables developers to define flexible, type-safe configuration interfaces throughout the platform. Options provide a declarative way to capture custom information from users while maintaining consistency across all components.

## What Are Options?

Options are **configuration parameters** that allow you to:

* Capture user input in a structured, validated way
* Define custom properties for components (assistants, modules, steps)
* Add configurable fields to taxonomies (data elements)
* Create dynamic form interfaces without writing UI code
* Enable users to configure components directly in the platform UI

Think of options as a **schema language for user configuration** - you describe what you need, and Kodexa automatically generates the appropriate UI controls and validation.

## The Options Flow

```text theme={null}
Developer defines options → Platform generates UI → User configures → Values passed to code
     (in metadata)           (automatically)         (in UI)          (at runtime)
```

### Example: Simple Assistant with Options

**Developer defines** (in assistant metadata):

```yaml theme={null}
options:
  - name: hostname
    type: string
    label: SFTP Hostname
    description: The hostname of the SFTP server
    required: true
  - name: port
    type: number
    label: Port
    description: Port number for SFTP connection
    default: 22
```

**Platform generates**: Text input field + numeric input field with validation

**User configures**: Enters "sftp.example.com" and "2222"

**Code receives**: `{'hostname': 'sftp.example.com', 'port': 2222}`

## Where Are Options Used?

Options appear throughout the Kodexa platform:

### 1. **Assistants**

Define configuration parameters for assistant behavior:

```yaml theme={null}
- slug: data-publisher
  type: assistant
  options:
    - name: schedule
      type: string
      label: Publication Schedule
    - name: format
      type: select
      possibleValues:
        - label: JSON
          value: json
        - label: CSV
          value: csv
```

### 2. **Modules**

Configure inference and training behavior:

```yaml theme={null}
metadata:
  type: module
  inferOptions:
    - name: confidence_threshold
      type: number
      label: Confidence Threshold
      default: 0.85
      description: Minimum confidence score for predictions
  trainOptions:
    - name: epochs
      type: number
      label: Training Epochs
      default: 10
```

### 3. **Taxonomies (Data Definitions)**

Add custom properties to data elements:

```yaml theme={null}
taxons:
  - label: Invoice
    path: /invoice
    options:
      - name: required
        type: boolean
        label: Required Field
        default: false
      - name: validation_rule
        type: select
        label: Validation Rule
        possibleValues:
          - label: None
            value: none
          - label: Numeric Only
            value: numeric
          - label: Date Format
            value: date
```

When users label documents, they can set these properties on each labeled instance.

### 4. **Actions**

Configure executable actions:

```yaml theme={null}
- slug: send-email
  type: action
  options:
    - name: recipient
      type: string
      label: Email Recipient
      required: true
    - name: subject
      type: string
      label: Subject Line
```

### 5. **Pipeline Steps**

Configure processing steps in pipelines:

```yaml theme={null}
steps:
  - stepRef: normalize-text
    options:
      - name: lowercase
        type: boolean
        default: true
      - name: remove_punctuation
        type: boolean
        default: false
```

## Core Option Structure

Every option has this basic structure:

```yaml theme={null}
- name: option_name           # Key used to access the value in code
  type: string                # Option type (determines UI control)
  label: Display Name         # Shown to users
  description: Help text      # Explains what this option does
  required: false             # Whether value is mandatory
  default: default_value      # Pre-filled value
```

### Required Fields

* **name**: Unique identifier for the option (used in code to access the value)
* **type**: Determines which UI control to render and how to validate input
* **label**: User-facing display name
* **description**: Help text explaining the purpose and usage

### Optional Fields

* **required**: Boolean indicating if the option must be set (default: false)
* **default**: Pre-filled value shown to users
* **possibleValues**: Array of allowed values (for dropdowns/selects)
* **showIf**: Conditional visibility based on other option values
* **developerOnly**: Only show to users with developer privileges
* **featureFlag**: Gate option behind a feature flag
* **properties**: Additional metadata for option behavior (e.g., `collapsible: true`)

## Option Types Overview

Kodexa supports **24+ option types** organized into categories:

### Basic Input Types

* **string** / **text**: Single or multi-line text input
* **number**: Numeric input with optional min/max constraints
* **boolean**: Checkbox or toggle switch
* **select**: Dropdown selection from predefined values

### Code & Script Types

* **code**: Full code editor with syntax highlighting
* **script**: Script input (supports multiple languages)

### Platform-Specific Types

* **documentStore**: Select a document store
* **moduleStore**: Select a module store
* **tableStore**: Select a data store
* **taxonomyStore**: Select a taxonomy (data definition)
* **document**: Search and select a specific document
* **workspace**: Select a workspace

### Taxonomy Types

* **taxon**: Select a taxonomy element
* **taxon\_label**: Select a taxonomy label
* **taxon\_with\_properties**: Select taxonomy + configure properties
* **taxon-lookup**: Hierarchical taxonomy search

### Status & State Types

* **documentStatus**: Select document status
* **attributeStatus**: Select attribute status
* **taskStatus**: Select task status

### Advanced Types

* **cloud-model**: Select cloud-based AI model (with caching)
* **cloud-embedding**: Select embedding model
* **pipeline**: Configure entire pipeline
* **pipelineModuleOptions**: Configure multiple modules in pipeline
* **data-form**: Select data form configuration

### Display Types

* **alert**: Display informational message
* **article**: Embed knowledge base article

## Nested Options (Option Groups)

Options can be **nested into groups** for better organization:

```yaml theme={null}
options:
  - name: connection_settings
    type: object
    label: Connection Settings
    description: Database connection configuration
    properties:
      collapsible: true  # Can be collapsed in UI
    groupOptions:
      - name: host
        type: string
        label: Database Host
        required: true
      - name: port
        type: number
        label: Database Port
        default: 5432
      - name: use_ssl
        type: boolean
        label: Use SSL
        default: true
```

This creates a collapsible section containing three related options.

## Conditional Visibility

Use `showIf` to show/hide options based on other values:

```yaml theme={null}
options:
  - name: use_custom_endpoint
    type: boolean
    label: Use Custom Endpoint
    default: false

  - name: endpoint_url
    type: string
    label: Custom Endpoint URL
    showIf: "this.use_custom_endpoint === true"
    # Only shown when use_custom_endpoint is checked
```

The `showIf` field accepts JavaScript expressions evaluated against the current option values.

## Possible Values (Constrained Choices)

Limit user input to predefined choices:

```yaml theme={null}
- name: output_format
  type: string
  label: Output Format
  description: Format for exported data
  possibleValues:
    - label: JSON
      value: json
    - label: CSV
      value: csv
    - label: XML
      value: xml
```

Renders as a dropdown with only these three options.

## Developer-Only Options

Hide advanced options from regular users:

```yaml theme={null}
- name: debug_mode
  type: boolean
  label: Enable Debug Logging
  developerOnly: true  # Only visible to users with "Show Developer Tools" enabled
```

## Accessing Option Values in Code

### In Python (Assistants/Modules)

```python theme={null}
class MyAssistant:
    def __init__(self, options):
        # Options are passed as a dictionary
        self.hostname = options.get('hostname')
        self.port = options.get('port', 22)  # With default
        self.use_ssl = options.get('use_ssl', False)

    def run(self, context):
        # Use the configured values
        connection = connect(
            host=self.hostname,
            port=self.port,
            ssl=self.use_ssl
        )
```

### In Metadata (Other Components)

Options can reference each other or be used in expressions:

```yaml theme={null}
pipeline:
  steps:
    - stepRef: process-documents
      options:
        input_store: ${parent.options.source_store}  # Reference parent option
```

## Best Practices

### 1. **Provide Clear Labels and Descriptions**

```yaml theme={null}
# Good
- name: retry_count
  label: Maximum Retry Attempts
  description: Number of times to retry failed operations before giving up

# Poor
- name: retry_count
  label: Retry Count
  description: Retries
```

### 2. **Use Appropriate Types**

```yaml theme={null}
# Good - type matches the data
- name: port
  type: number

# Poor - storing number as string
- name: port
  type: string
```

### 3. **Set Sensible Defaults**

```yaml theme={null}
- name: timeout
  type: number
  label: Request Timeout (seconds)
  default: 30  # Most users won't need to change this
```

### 4. **Group Related Options**

```yaml theme={null}
- name: email_settings
  type: object
  label: Email Configuration
  groupOptions:
    - name: smtp_host
      type: string
    - name: smtp_port
      type: number
    - name: use_tls
      type: boolean
```

### 5. **Use `required` Judiciously**

Only mark options as required if the component truly cannot function without them.

```yaml theme={null}
- name: api_key
  type: string
  label: API Key
  required: true  # Component cannot work without this

- name: log_level
  type: select
  label: Log Level
  required: false  # Has a reasonable default
  default: info
```

### 6. **Leverage Conditional Visibility**

Keep the UI clean by hiding irrelevant options:

```yaml theme={null}
- name: use_proxy
  type: boolean
  label: Use HTTP Proxy

- name: proxy_url
  type: string
  label: Proxy URL
  showIf: "this.use_proxy === true"

- name: proxy_auth
  type: boolean
  label: Proxy Requires Authentication
  showIf: "this.use_proxy === true"
```

## How Options Enable Custom Information Capture

The Options system is powerful because it provides **declarative configuration**:

1. **No UI Code Required**: Define options in YAML, get a UI automatically
2. **Type Safety**: Platform validates input based on option type
3. **Consistency**: Same option types look and behave the same everywhere
4. **Discoverability**: Users see configuration options in context
5. **Versioning**: Options are part of component metadata (versioned with the component)

### Example: Custom Data Capture

Suppose you're building a custom invoice extraction module. You want users to configure:

* Which fields are required
* Validation rules per field
* Output format preferences

**Without options**, you'd need to:

1. Build a custom UI
2. Handle validation
3. Store configuration somewhere
4. Pass configuration to your module code

**With options**, you simply:

```yaml theme={null}
metadata:
  type: module
  inferOptions:
    - name: required_fields
      type: taxon_with_properties
      label: Required Fields
      description: Mark which invoice fields must be present

    - name: validation_rules
      type: object
      label: Validation Rules
      groupOptions:
        - name: validate_dates
          type: boolean
          default: true
        - name: validate_amounts
          type: boolean
          default: true

    - name: output_format
      type: select
      label: Output Format
      possibleValues:
        - label: JSON
          value: json
        - label: Structured CSV
          value: csv
```

Kodexa generates the UI, validates input, and passes the configuration to your module.

## Next Steps

* **[Working with Options](/guides/reference/working-with-options)**: Complete reference of all option types
* **[Advanced Options Features](/guides/reference/options-advanced-features)**: Deep dive into grouping, conditionals, and complex patterns
* **[Defining an Assistant](/concepts/defining_an_assistant)**: See options in action for assistants

## Summary

The Options system is Kodexa's declarative configuration language. By defining options in metadata, you:

* Enable users to configure your components without code changes
* Provide a consistent, validated configuration experience
* Capture custom information tailored to your use case
* Keep configuration co-located with component definitions

Options turn **configuration from a UI development task into a metadata declaration**, allowing you to focus on building functionality rather than forms.