> ## 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.

# Knowledge Item Types

> Knowledge Item Types in Kodexa define configurable capabilities and behaviors for document processing, customizing extraction, prompts, and workflows.

A **Knowledge Item Type** is a template that defines a configurable capability in the system. While [Knowledge Feature Types](/concepts/knowledge_feature_types) describe *what you know* about documents, Knowledge Item Types describe *what you can do* - such as customizing extraction prompts, applying validation rules, or modifying processing behavior.

## When Do You Need Item Types?

Create a Knowledge Item Type when you want to:

* Allow customization of extraction prompts for specific data elements
* Define validation rules that can be selectively applied
* Create processing behaviors that can be configured per document type
* Enable business users to customize system behavior without code changes

## How Item Types Work

```mermaid theme={null}
flowchart LR
    subgraph "Define Capability"
        IT[Knowledge Item Type<br/>"Prompt Override"]
    end

    subgraph "Configure Instances"
        I1[Item: "SEC 10K Prompt"]
        I2[Item: "Invoice Total Prompt"]
        I3[Item: "Contract Date Prompt"]
    end

    subgraph "Apply via Knowledge Set"
        KS[Knowledge Set]
    end

    subgraph "Affects Processing"
        DOC[Document Processing]
    end

    IT --> I1
    IT --> I2
    IT --> I3

    I1 --> KS
    I2 --> KS
    KS --> DOC
```

1. **Define the Type** - Create a Knowledge Item Type that describes a capability (e.g., "Prompt Override")
2. **Create Items** - Create configured instances with specific values (e.g., "Use this prompt for invoice totals")
3. **Connect via Sets** - Knowledge Sets link Features to Items, triggering behaviors based on document characteristics

## Item Type Structure

| Field         | Purpose                                | Example                                              |
| ------------- | -------------------------------------- | ---------------------------------------------------- |
| `slug`        | Unique identifier                      | `prompt-override`                                    |
| `name`        | Display name                           | `Prompt Override`                                    |
| `description` | What this capability does              | `Customize the extraction prompt for a data element` |
| `options`     | Configuration parameters users can set | `targetField`, `promptText`, `model`                 |

### Options Define Configuration

Options specify what parameters users can configure when creating items:

```yaml theme={null}
options:
  - name: targetField
    type: string
    label: Target Field
    description: The data element this prompt applies to
    required: true
  - name: promptText
    type: text
    label: Prompt Text
    description: The custom prompt to use for extraction
    required: true
  - name: temperature
    type: number
    label: Temperature
    description: LLM temperature setting (0-1)
    default: 0.1
```

## Creating an Item Type

### Via YAML (GitOps)

Create a file in `kodexa-resources/knowledge-item-types/`:

```yaml theme={null}
# kodexa-resources/knowledge-item-types/prompt-override.yaml
slug: prompt-override
name: Prompt Override
description: Customize the extraction prompt for a specific data element

options:
  - name: targetField
    type: string
    label: Target Field
    description: The taxon path this prompt applies to
    required: true

  - name: promptText
    type: text
    label: Prompt Text
    description: The custom prompt to use for extraction
    required: true

  - name: includeExamples
    type: boolean
    label: Include Examples
    description: Whether to include few-shot examples
    default: true
```

Add to your manifest:

```yaml theme={null}
# manifests/main.yaml
resources:
  knowledge-item-types:
    - prompt-override
```

Deploy:

```bash theme={null}
kdx sync deploy
```

### Via API

```bash theme={null}
curl -X POST "https://platform.kodexa.ai/api/knowledgeItemTypes" \
  -H "Authorization: Bearer $KODEXA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "prompt-override",
    "name": "Prompt Override",
    "description": "Customize the extraction prompt for a specific data element",
    "options": [
      {
        "name": "targetField",
        "type": "string",
        "label": "Target Field",
        "required": true
      },
      {
        "name": "promptText",
        "type": "text",
        "label": "Prompt Text",
        "required": true
      }
    ]
  }'
```

### Via Kodexa UI

1. Navigate to **Knowledge** in the sidebar
2. Click **Item Types**
3. Click **Create Item Type**
4. Fill in name, slug, description
5. Add options to define configurable parameters
6. Save

## Creating Knowledge Items

Once you have an Item Type, create configured items:

### Via YAML

```yaml theme={null}
# Knowledge Item configuration
title: SEC 10K Extraction Prompt
description: Specialized prompt for extracting data from SEC 10K filings
knowledgeItemType: prompt-override
active: true

properties:
  targetField: "financial/revenue"
  promptText: |
    Extract the total revenue figure from this SEC 10K filing.
    Look for "Total Revenue", "Net Revenue", or "Total Sales" in the
    financial statements section. Return the most recent fiscal year value.
  includeExamples: true
```

### Via API

```bash theme={null}
curl -X POST "https://platform.kodexa.ai/api/knowledgeItems" \
  -H "Authorization: Bearer $KODEXA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SEC 10K Extraction Prompt",
    "description": "Specialized prompt for extracting data from SEC 10K filings",
    "knowledgeItemTypeSlug": "prompt-override",
    "active": true,
    "properties": {
      "targetField": "financial/revenue",
      "promptText": "Extract the total revenue figure from this SEC 10K filing...",
      "includeExamples": true
    }
  }'
```

## Connecting Items to Features via Knowledge Sets

Knowledge Items don't do anything on their own - they need to be connected to documents through **Knowledge Sets**. A Knowledge Set says "when a document has *these features*, apply *these items*."

```mermaid theme={null}
flowchart LR
    F[Feature<br/>"Document Type = 10K"] --> KS[Knowledge Set]
    KS --> I[Item<br/>"SEC 10K Prompt"]

    DOC[Document with<br/>type = 10K] -.-> F
    I -.-> DOC
```

See [Knowledge Sets](/concepts/knowledge_system) for details on creating sets.

## Common Item Type Examples

### Validation Rule

```yaml theme={null}
slug: validation-rule
name: Validation Rule
description: Apply custom validation logic to extracted data

options:
  - name: targetField
    type: string
    label: Target Field
    required: true

  - name: ruleType
    type: select
    label: Rule Type
    options:
      - value: required
        label: Required Field
      - value: range
        label: Numeric Range
      - value: pattern
        label: Regex Pattern
      - value: custom
        label: Custom Expression

  - name: ruleExpression
    type: string
    label: Rule Expression
    description: The validation expression or pattern

  - name: errorMessage
    type: string
    label: Error Message
    description: Message shown when validation fails
```

### Field Ignore Rule

```yaml theme={null}
slug: field-ignore
name: Field Ignore Rule
description: Skip extraction for specific fields under certain conditions

options:
  - name: targetField
    type: string
    label: Target Field
    required: true

  - name: reason
    type: string
    label: Reason
    description: Why this field should be ignored
```

### Processing Priority

```yaml theme={null}
slug: processing-priority
name: Processing Priority
description: Adjust processing priority for specific document types

options:
  - name: priority
    type: select
    label: Priority Level
    options:
      - value: high
        label: High Priority
      - value: normal
        label: Normal
      - value: low
        label: Low Priority

  - name: slaHours
    type: number
    label: SLA (Hours)
    description: Target processing time in hours
```

## Item Types vs Feature Types

| Aspect          | Feature Type                         | Item Type                            |
| --------------- | ------------------------------------ | ------------------------------------ |
| **Purpose**     | Capture metadata about documents     | Define configurable behaviors        |
| **Direction**   | Information FROM documents           | Actions applied TO documents         |
| **Examples**    | Vendor, Document Type, Language      | Prompt Override, Validation Rule     |
| **Persistence** | Features are reused across documents | Items are applied via Knowledge Sets |
| **Created by**  | Often by agents during processing    | Typically by developers/admins       |

## Next Steps

* [Knowledge Feature Types](/concepts/knowledge_feature_types) - Define document metadata categories
* [Customizing Extraction](/concepts/customizing_extraction) - End-to-end guide using Item Types
* [Adding Validation Rules](/concepts/adding_validation_rules) - Practical validation example