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

# Platform Models

> Auto-generated Pydantic models for the Kodexa Platform API providing type-safe access to all platform resources from the Python SDK.

The Python SDK includes 959 Pydantic models auto-generated from the Kodexa API OpenAPI specification using `datamodel-codegen`. These models provide full type safety when working with the platform API.

## How They're Generated

The models in `kodexa_document.model._generated` are produced by running `datamodel-codegen` against the `api-docs.yaml` OpenAPI specification from `kodexa-api`. This happens as part of the CI pipeline and ensures the Python models always match the API.

## Importing Models

```python theme={null}
# Import specific models from the generated module
from kodexa_document.model._generated import (
    Organization,
    Project,
    Task,
    DocumentFamily,
    Assistant,
    Execution,
    User,
    Store,
)
```

## Key Model Categories

### Organizations & Projects

| Model          | Description                                            |
| -------------- | ------------------------------------------------------ |
| `Organization` | Organization with members, subscriptions, and settings |
| `Project`      | Project containing assistants, stores, and taxonomies  |
| `Membership`   | User membership in an organization                     |

### Assistants & Execution

| Model                 | Description                                    |
| --------------------- | ---------------------------------------------- |
| `Assistant`           | Assistant configuration within a project       |
| `AssistantDefinition` | Deployable assistant definition (module-level) |
| `Execution`           | An execution of an assistant pipeline          |
| `ExecutionEvent`      | Events emitted during execution                |

### Documents & Storage

| Model            | Description                                |
| ---------------- | ------------------------------------------ |
| `DocumentFamily` | A document family in a store               |
| `Store`          | Document or data store                     |
| `ContentObject`  | A content object (KDDB, native file, etc.) |

### Knowledge System

| Model                  | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `KnowledgeSet`         | A set of knowledge items                                   |
| `KnowledgeItem`        | An individual knowledge item                               |
| `KnowledgeFeature`     | A feature attached to knowledge items or document families |
| `KnowledgeItemType`    | Type definition for knowledge items                        |
| `KnowledgeFeatureType` | Type definition for knowledge features                     |

### Tasks & Workflow

| Model                | Description                                      |
| -------------------- | ------------------------------------------------ |
| `Task`               | A workflow task                                  |
| `TaskTemplate`       | Template for creating tasks                      |
| `TaskActivity`       | Activity log entry for a task                    |
| `TaskDocumentFamily` | Association between a task and a document family |

### Users & Access

| Model              | Description                             |
| ------------------ | --------------------------------------- |
| `User`             | Platform user                           |
| `PlatformOverview` | Platform configuration and version info |

## KodexaBaseModel

All generated models inherit from `KodexaBaseModel`, which extends Pydantic's `BaseModel` with:

### camelCase / snake\_case Support

Models accept both camelCase (matching the JSON API) and snake\_case (Pythonic) field names:

```python theme={null}
from kodexa_document.model._generated import Organization

# Both work - populate_by_name=True
org = Organization(name="Acme Corp", slug="acme")
org = Organization(**{"name": "Acme Corp", "slug": "acme"})

# API response with camelCase also works
org = Organization(**{
    "name": "Acme Corp",
    "organizationType": "BUSINESS"
})
```

### Dict-like Access

Models support dict-style bracket access and `get()`:

```python theme={null}
org = Organization(name="Acme Corp")

# Dict-like access
name = org["name"]
org["name"] = "New Name"

# Safe get with default
value = org.get("missing_field", "default")

# Containment check
if "name" in org:
    print(org["name"])
```

### Extra Fields

The `extra='allow'` configuration means models accept fields not in the schema without raising errors. This handles forward-compatibility when the API adds new fields.

## Taxonomy and Taxon Extensions

The SDK extends the generated `TaxonomyBase` and `TaxonBase` models with navigation methods. These are imported from the top-level package, not from `_generated`:

```python theme={null}
from kodexa_document import Taxonomy

taxonomy_data = {
    "name": "Invoice",
    "slug": "invoice",
    "taxons": [
        {
            "name": "Header",
            "taxonType": "GROUP",
            "children": [
                {"name": "Invoice Number", "taxonType": "STRING"},
                {"name": "Date", "taxonType": "DATE"},
                {"name": "Total", "taxonType": "DECIMAL"}
            ]
        }
    ]
}

taxonomy = Taxonomy(**taxonomy_data)
taxonomy.update_paths()

# Find a taxon by path
total = taxonomy.get_taxon_by_path("/Header/Total")
print(total.name)  # "Total"

# Get all group taxons
groups = taxonomy.taxons[0].groups()

# Navigate with path parts
date = taxonomy.taxons[0].find_taxon("Date")
```

### Taxon Methods

| Method                       | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `update_path(parent_path)`   | Recursively sets `path` on this taxon and its children |
| `find_taxon(*path_parts)`    | Search children by name at each level                  |
| `get_taxon_by_path(path)`    | Find a taxon matching the exact path string            |
| `groups()`                   | Return all group-type taxons at this level and below   |
| `get_simplified_structure()` | Return a minimal dict representation                   |

### Taxonomy Methods

| Method                    | Description                                  |
| ------------------------- | -------------------------------------------- |
| `get_taxon_by_path(path)` | Search all root taxons and children by path  |
| `update_paths()`          | Call `update_path()` on every root taxon     |
| `build_guidance_tags()`   | Build `{path: [examples]}` dict for guidance |

## Deserializing API Responses

The models integrate naturally with API response data:

```python theme={null}
import requests
from kodexa_document.model._generated import Project

# Fetch from API
response = requests.get(
    "https://platform.kodexa.ai/api/projects/abc-123",
    headers={"X-API-Key": "your-token"}
)

# Deserialize into typed model
project = Project(**response.json())
print(project.name)
print(project.slug)
```

For the full platform client experience with pagination, authentication, and endpoint helpers, see the [Platform Client](/sdk/python/platform-client) page.

## DateTime Handling

`KodexaBaseModel` uses a custom `StandardDateTime` type that serializes datetimes to millisecond-precision ISO 8601 strings with `Z` suffix (e.g., `2026-01-15T10:30:00.000Z`). This matches the Java/Go API format.