> ## 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 489 Pydantic models and 29 enumeration classes 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; carries `status_slug` rather than an embedded status          |
| `TaskStatus`             | An organization's task status (label, color, `status_type`)                    |
| `TaskTemplate`           | Template for creating tasks                                                    |
| `TaskActivity`           | Activity log entry for a task                                                  |
| `TaskDocumentFamily`     | Association between a task and a document family, positioned by `ordinal`      |
| `ActivityDocumentFamily` | Association between an activity and a document family, positioned by `ordinal` |

### Users & Access

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

## Request Models

Alongside the response model for each resource, the generated module contains a
`<Entity>CreateRequest` and an `<Entity>UpdateRequest`, so a create or update
payload can be built from a model that holds only the fields the server accepts:

* **`<Entity>`** — the response shape, everything the API returns.
* **`<Entity>CreateRequest`** — for `POST` bodies. Server-generated fields
  (`id`, `uuid`, `createdOn`, `updatedOn`, `changeSequence`) are absent, so they
  cannot be sent by accident.
* **`<Entity>UpdateRequest`** — for `PUT` bodies. Keeps `changeSequence` for
  optimistic locking and omits the ownership fields an update never writes (for
  example `projectId` on a task).

```python theme={null}
from kodexa_document.model._generated import (
    TaskCreateRequest,
    TaskUpdateRequest,
)

# Create payload — no server-generated fields to leave blank
new_task = TaskCreateRequest(
    projectId="a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    title="Review Q4 invoices",
    statusSlug="in-review",
)

# Update payload — carries the change sequence you read back
change = TaskUpdateRequest(
    title="Review Q4 invoices (revised)",
    changeSequence=7,
)
```

Which fields the server requires is described by the API specification served at
`GET /v3/api-docs`; the generated Python models leave every field optional so that
partial payloads remain expressible.

## Enumerations

Enumeration classes take their names from the API specification rather than from
generator-invented ones, so each enum has one stable name across every generated
client. They are `StrEnum` subclasses, so a member compares equal to its wire
string.

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

TaskStatusType.OPEN == "OPEN"  # True
```

| Enumeration                                                  | Covers                                              |
| ------------------------------------------------------------ | --------------------------------------------------- |
| `ExecutionStatus`                                            | Execution lifecycle state                           |
| `ExecutionStatusMessageType`                                 | Type of an execution status message                 |
| `TaskStatusType`                                             | `OPEN`, `IN_PROGRESS`, `DONE`, `BLOCKED`, `PENDING` |
| `TaskActivityType`                                           | Kind of task activity entry                         |
| `TaskSignalOutcome`                                          | Reviewer signal outcome                             |
| `SortDirection`                                              | Sort order on list endpoints                        |
| `AuditAction`                                                | Action recorded in an audit entry                   |
| `DocumentActorType`                                          | Who acted on a document                             |
| `TaxonCardinality` / `TaxonValuePath` / `TaxonMetadataValue` | Taxon configuration                                 |
| `AnalyticsFieldType` / `AnalyticsMetricType`                 | Analytics dataset field and metric types            |
| `WebLlmModelSize`                                            | Model size for browser-side models                  |
| `SessionState`                                               | Session lifecycle state                             |
| `PipelineStepType`                                           | Kind of pipeline step                               |
| `ChatMessageRole`                                            | Author role on a chat message                       |

### Renamed enumerations

If you import enum classes by their old generated names, update the imports:

| Previous name               | Current name         |
| --------------------------- | -------------------- |
| `Status`                    | `ExecutionStatus`    |
| `StatusType4`               | `TaskStatusType`     |
| `Type6`                     | `TaskActivityType`   |
| `Direction`                 | `SortDirection`      |
| `Action`                    | `AuditAction`        |
| `ActorType`                 | `DocumentActorType`  |
| `Cardinality`               | `TaxonCardinality`   |
| `ValuePath`                 | `TaxonValuePath`     |
| `MetadataValue`             | `TaxonMetadataValue` |
| `AnalyticsDatasetFieldType` | `AnalyticsFieldType` |
| `ModelType`                 | `WebLlmModelSize`    |
| `Outcome`                   | `TaskSignalOutcome`  |
| `State`                     | `SessionState`       |
| `StepType`                  | `PipelineStepType`   |

`ExecutionStatus` is also exported from the top level, so
`from kodexa_document.model import ExecutionStatus` works. The values on the wire
are unchanged — only the Python type names are.

## Task Status

`Task` carries the status as `status_slug` only. Resolve the label, color and
`status_type` through the organization's task statuses:

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

task = client.tasks.get("task-id-123")

response = client.get(
    "/api/task-statuses",
    params={"filter": f"organization.id:'{organization_id}'", "pageSize": 100},
)
statuses = {s["slug"]: TaskStatus(**s) for s in response.json()["content"]}

status = statuses.get(task.status_slug)
if status:
    print(status.label, status.color, status.status_type)
```

To move a task to another status, pass the `TaskStatus` to the task endpoint's
`update_status()`, which sends the slug for you.

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