# Understanding Koncile's Structure

Before diving into the API, it's important to understand how Koncile organizes document extraction.

#### The Hierarchy

```
Company
└── Folders 
    └── Templates
        ├── Fields
        └── Instructions
```

| Concept         | Purpose                                                                        | Example                                            |
| --------------- | ------------------------------------------------------------------------------ | -------------------------------------------------- |
| **Folder**      | Organizes templates by document category                                       | "Supplier Invoices", "Purchase Orders", "Receipts" |
| **Template**    | Defines extraction rules for a specific document type                          | "Acme Corp Invoice", "Standard PO Template"        |
| **Field**       | A specific piece of data to extract, can be General or Line                    | "Invoice Number", "Total Amount", "Supplier Name"  |
| **Instruction** | Custom guidance for the AI extractor that is applied to General or Line fields | Always skip the first page of the document         |

#### How It Works

When you upload a document:

1. Koncile identifies which **template** to use (either specified by you or auto-detected)
2. The AI reads the document and extracts values for each **field** defined in the template
3. Results are returned with extracted values and confidence scores

#### Field & Instruction Types Explained

Koncile supports two types of fields:

| Type               | When to Use                          | Examples                                                  |
| ------------------ | ------------------------------------ | --------------------------------------------------------- |
| **General fields** | Data that appears once per document  | Invoice number, invoice date, supplier name, total amount |
| **Line fields**    | Data that repeats for each line item | Product name, quantity, unit price, line total            |

For example, on an invoice:

* The invoice number appears once → **General field**
* Each product line has its own name, quantity, and price → **Line fields**

An instruction that has a type **General field** only concerns the **General fields**. Same logic for the Line fields

#### Field Formats

Each field has a format that helps the AI understand what type of data to extract:

| Format            | Description                       | Use Case                                                                            |
| ----------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
| `text`            | Free-form text                    | Names, descriptions, addresses                                                      |
| `number`          | Numeric values                    | Amounts, quantities, percentages                                                    |
| `date`            | Date values                       | Invoice dates, due dates                                                            |
| `boolean`         | True/false                        | Checkboxes, yes/no fields                                                           |
| `multiple_choice` | Selection from predefined options | Payment terms, document status                                                      |
| `unit`            | Unit of measurement               | kg, liters, pieces                                                                  |
| `empty`           | Placeholder                       | If you want the field to appear in your ouput data but don't need to extract values |
