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

# Python SDK

> Install and configure the Kodexa Document Python SDK (kodexa-document) to build document processing apps backed by a high-performance Go core via CFFI.

The Kodexa Document Python SDK (`kodexa-document`) provides a high-performance library for working with KDDB documents and the Kodexa platform. Built on a Go backend with Python bindings via CFFI, it delivers exceptional performance while maintaining a Pythonic API.

## Architecture

The SDK has a layered architecture:

* **Go Core** — Document storage (KDDB/SQLite), content tree operations, extraction engine, and delta tracking are implemented in Go for performance
* **CFFI Bridge** — Python calls into the Go shared library via CFFI, with automatic handle management using `weakref.finalize`
* **Pydantic Models** — 959 platform models are auto-generated from the OpenAPI spec using `datamodel-codegen`, providing full type safety
* **Platform Client** — A REST client for interacting with the Kodexa API, built on the generated models

## Requirements

* **Python 3.12 or higher**
* pip (Python package manager)

## Installation

Install the SDK from PyPI:

```bash theme={null}
pip install kodexa-document
```

<Note>
  The package includes pre-built native libraries for Linux, macOS, and Windows. No compilation or Go installation required.
</Note>

### Optional Dependencies

Install additional features as needed:

```bash theme={null}
# Development tools (pytest, black, mypy, etc.)
pip install kodexa-document[dev]

# Testing only
pip install kodexa-document[test]

# Platform integrations (requests, numpy, pydantic-yaml)
pip install kodexa-document[platform]
```

## Verify Installation

Test your installation:

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

# Create a new document
with Document() as doc:
    print(f"Document UUID: {doc.uuid}")
    print(f"Version: {doc.version}")
```

## Module Organization

The SDK is organized into several subsystems:

| Module              | Import Path                        | Description                                                                                                               |
| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Core Document**   | `kodexa_document`                  | `Document`, `ContentNode`, `ContentFeature`, `Tag`                                                                        |
| **Extraction**      | `kodexa_document`                  | `ExtractionEngine`, `Taxonomy`, `DataObject`, `DataAttribute`                                                             |
| **Accessors**       | `kodexa_document`                  | `DataObjectAccessor`, `DataAttributeAccessor`, `AuditAccessor`, `DeltaAccessor`, `NoteAccessor`, `NativeDocumentAccessor` |
| **Transactions**    | `kodexa_document`                  | `TransactionContext`, `BatchTransactionContextManager`                                                                    |
| **Processing**      | `kodexa_document`                  | `ProcessingStep`, `KnowledgeItem`, `KnowledgeFeature`                                                                     |
| **Platform Models** | `kodexa_document.model._generated` | 959 auto-generated Pydantic models (`Organization`, `Project`, `Task`, etc.)                                              |
| **Platform Client** | `kodexa_document.platform`         | `KodexaClient`, `KodexaPlatform` (lazy import)                                                                            |
| **LLM**             | `kodexa_document.llm`              | `ModelManager`, `ChatMessage`, `LLMUsageMetrics` (lazy import)                                                            |

<Note>
  Platform, LLM, and assistant modules use lazy imports to avoid pulling in heavy dependencies. Import them explicitly when needed:

  ```python theme={null}
  from kodexa_document.platform import KodexaClient, KodexaPlatform
  ```
</Note>

## Key Imports

The most commonly used imports from the top-level package:

```python theme={null}
from kodexa_document import (
    # Core
    Document, ContentNode, ContentFeature, Tag,

    # Extraction
    ExtractionEngine, Taxonomy, DataObject, DataAttribute, DataException,

    # Accessors
    DataObjectAccessor, DataAttributeAccessor, AuditAccessor,
    DeltaAccessor, NativeDocumentAccessor, NoteAccessor,

    # Transactions
    TransactionContext, BatchTransactionContextManager,

    # Processing
    ProcessingStep,

    # Errors
    DocumentError, DocumentNotFoundError, ExtractionError,
)
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/sdk/python/getting-started">
    Learn the basics of creating and manipulating documents
  </Card>

  <Card title="Platform Models" icon="cubes" href="/sdk/python/platform-models">
    Auto-generated Pydantic models from the OpenAPI spec
  </Card>

  <Card title="Platform Client" icon="server" href="/sdk/python/platform-client">
    REST API client for the Kodexa platform
  </Card>

  <Card title="Extraction" icon="magnifying-glass" href="/sdk/python/extraction">
    Extract structured data from documents using taxonomies
  </Card>

  <Card title="Processing" icon="gears" href="/sdk/python/processing">
    Track processing steps and knowledge items
  </Card>

  <Card title="LLM & Model Manager" icon="brain" href="/sdk/python/llm">
    Access large language models through the AI Gateway
  </Card>
</CardGroup>

## Package Information

| Property     | Value                                                                                |
| ------------ | ------------------------------------------------------------------------------------ |
| Package Name | `kodexa-document`                                                                    |
| PyPI         | [pypi.org/project/kodexa-document](https://pypi.org/project/kodexa-document)         |
| License      | Apache-2.0                                                                           |
| Repository   | [github.com/kodexa-ai/kodexa-document](https://github.com/kodexa-ai/kodexa-document) |