Skip to main content

​
Knowledge Item Types

A Knowledge Item Type is a template that defines a configurable capability in the system. While 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

  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

FieldPurposeExample
slugUnique identifierprompt-override
nameDisplay namePrompt Override
descriptionWhat this capability doesCustomize the extraction prompt for a data element
optionsConfiguration parameters users can settargetField, promptText, model

​
Options Define Configuration

Options specify what parameters users can configure when creating items: 
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/: 
# 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: 
# manifests/main.yaml
resources:
  knowledge-item-types:
    - prompt-override
Deploy: 
kdx sync deploy

​
Via API

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

# 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

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.” See Knowledge Sets for details on creating sets.

​
Common Item Type Examples

​
Validation Rule

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

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

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

AspectFeature TypeItem Type
PurposeCapture metadata about documentsDefine configurable behaviors
DirectionInformation FROM documentsActions applied TO documents
ExamplesVendor, Document Type, LanguagePrompt Override, Validation Rule
PersistenceFeatures are reused across documentsItems are applied via Knowledge Sets
Created byOften by agents during processingTypically by developers/admins

​
Next Steps