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.
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
# 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:
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():
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='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:
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:
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)
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.