--- title: "Vision" canonical_url: "https://www.nutrient.io/api/python/vision/" md_url: "https://www.nutrient.io/api/python/vision.md" last_updated: "2026-08-11T08:57:05.212Z" description: "Provides machine learning and computer vision capabilities for document processing. Enables AI-powered document description and content extraction." --- Provides machine learning and computer vision capabilities for document processing. Enables AI-powered document description and content extraction. ```python from nutrient_sdk import Vision ``` ## Construction `Vision` cannot be instantiated directly. Obtain instances through static factory methods or via other SDK classes. ## Class Methods ### classify_text ```python @classmethod def classify_text(cls, request: ClassificationRequest, text: str) -> str ``` Classifies caller-supplied text against the candidate labels carried by `request` (zero-shot) with no document. The text is scored directly by the text branch and the image branch is skipped, so nothing is rendered and no file is opened — use this when you already have the text (an email body, a database field, your own extraction pipeline) rather than a document on disk. **Parameters:** | Name | Type | Description | | --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | | `request` | [`ClassificationRequest`](/api/python/requests/classification-request/) | The classification request carrying at least two candidate labels. | | `text` | `str` | The text to classify. | **Returns:** `str` - JSON with the predicted label and the ranked candidate probabilities. --- ### detect_languages_text ```python @classmethod def detect_languages_text(cls, text: str) -> str ``` ```python @classmethod def detect_languages_text(cls, text: str, settings: DocumentSettings) -> str ``` Detects the language of caller-supplied text, fully offline, with no document. CLD3 scores the text directly — nothing is rendered and no file is opened. Use this when you already have the text (an email body, a database field, your own extraction pipeline) rather than a document on disk. **Parameters:** | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `text` | `str` | The text to detect the language of. | | `settings` *(optional)* | [`DocumentSettings`](/api/python/settings/document/document-settings/) | Document settings; `MaxLanguages` bounds how many languages are reported. | **Returns:** `str` - JSON with the predicted language and text direction. --- ### generate_schema ```python @classmethod def generate_schema(cls, request: SchemaGenerationRequest) -> str ``` ```python @classmethod def generate_schema(cls, request: SchemaGenerationRequest, settings: DocumentSettings) -> str ``` Generates a JSON Schema for a class of documents using a vision model, with default document settings. The schema is designed for downstream LLM structured-output extraction tasks: it is hard-clamped to the knobs in `SchemaGenerationSettings` and to the target structured-output dialect selected there, so the same call with the same settings always yields a schema the target accepts. **Parameters:** | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request` | [`SchemaGenerationRequest`](/api/python/requests/schema-generation-request/) | The schema generation request: the document type the schema must represent (required), an optional natural-language requirement, and up to five example documents used as grounding samples. | | `settings` *(optional)* | [`DocumentSettings`](/api/python/settings/document/document-settings/) | Document settings carrying `SchemaGenerationSettings` (schema shape and target dialect) and the vision model connection. | **Returns:** `str` - A JSON envelope object with a `schema` property (the generated JSON Schema) and a `constraints` array of cross-field rules in standard JsonLogic. The array is empty unless `SchemaGenerationSettings.IncludeConstraints` is enabled. --- ### generate_schema_to_file ```python @classmethod def generate_schema_to_file(cls, request: SchemaGenerationRequest, output_path: str) -> None ``` ```python @classmethod def generate_schema_to_file(cls, request: SchemaGenerationRequest, settings: DocumentSettings, output_path: str) -> None ``` Generates a JSON Schema for a class of documents using a vision model and writes it to a file, with default document settings. **Parameters:** | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request` | [`SchemaGenerationRequest`](/api/python/requests/schema-generation-request/) | The schema generation request: the document type the schema must represent (required), an optional natural-language requirement, and up to five example documents used as grounding samples. | | `output_path` | `str` | Path to the output file receiving the JSON Schema. | | `settings` *(optional)* | [`DocumentSettings`](/api/python/settings/document/document-settings/) | Document settings carrying `SchemaGenerationSettings` (schema shape and target dialect) and the vision model connection. | --- ### set ```python @classmethod def set(cls, document: Document) -> Vision ``` Creates a Vision instance for the specified document. **Parameters:** | Name | Type | Description | | ---------- | ----------------------------------- | -------------------------------------------------- | | `document` | [`Document`](/api/python/document/) | The document to analyze using vision capabilities. | **Returns:** [`Vision`](/api/python/vision/) - A Vision instance ready to perform analysis on the document. **Raises:** - [`NullOrEmptyParameterException`](/api/python/exceptions/null-or-empty-parameter-exception/): Thrown when document is null. --- ## Methods ### classify ```python def classify(self, request: ClassificationRequest) -> str ``` Classifies the document against the candidate labels carried by `request` (zero-shot) and exports the ranked result. Branch weights, supplied text, and the other knobs are read from `DocumentClassificationSettings` on the document's settings. The result is always JSON; `OutputFormat` is not consulted because only the JSON exporter serializes the classification result. **Parameters:** | Name | Type | Description | | --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | | `request` | [`ClassificationRequest`](/api/python/requests/classification-request/) | The classification request carrying at least two candidate labels. | **Returns:** `str` - The exported content as a string (JSON), including the predicted label and ranked candidate probabilities. --- ### classify_to_file ```python def classify_to_file(self, request: ClassificationRequest, output_path: str) -> None ``` Classifies the document against the candidate labels carried by `request` (zero-shot) and writes the exported result to a file. The result is always JSON; `OutputFormat` is not consulted because only the JSON exporter serializes the classification result. **Parameters:** | Name | Type | Description | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | | `request` | [`ClassificationRequest`](/api/python/requests/classification-request/) | The classification request carrying at least two candidate labels. | | `output_path` | `str` | Path to the output file. | --- ### describe ```python def describe(self) -> str ``` Generates an AI-powered description of the document content. **Returns:** `str` - A string containing the document description. --- ### detect_forms ```python def detect_forms(self) -> str ``` Detects form fields on the document and exports the result. Output format is determined by `OutputFormat` (JSON or IR Lite). Each detected field carries its type and bounding box. To also assign AI semantic labels (e.g. "First name"), set `FormLabelingSettings.EnableAiLabeling` on the document's settings before calling — no separate method is needed. **Returns:** `str` - The exported content as a string (JSON or IR Lite JSON depending on settings). --- ### detect_forms_to_file ```python def detect_forms_to_file(self, output_path: str) -> None ``` Detects form fields on the document and writes the exported result to a file. Output format is determined by `OutputFormat` (JSON or IR Lite). **Parameters:** | Name | Type | Description | | ------------- | ----- | ------------------------ | | `output_path` | `str` | Path to the output file. | --- ### detect_languages ```python def detect_languages(self) -> str ``` Detects the language and text direction of the document, fully offline, and exports the result. Runs the offline cascade (Tesseract OSD for script → script-model OCR → fastText for the specific language) on every page and reports one detection per page. Output format is determined by `OutputFormat`. **Returns:** `str` - JSON with the predicted language, text direction, and per-page detections. --- ### detect_languages_to_file ```python def detect_languages_to_file(self, output_path: str) -> None ``` Detects the language and text direction of the document, fully offline, and writes the exported result to a file. Output format is determined by `OutputFormat`. **Parameters:** | Name | Type | Description | | ------------- | ----- | ------------------------ | | `output_path` | `str` | Path to the output file. | --- ### extract_content ```python def extract_content(self) -> str ``` ```python def extract_content(self, settings: DocumentLayoutJsonExportSettings) -> str ``` Extracts structured content from the document using machine vision processing. The pipeline used is determined by the `Engine` setting and the output format by `OutputFormat`. **Parameters:** | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `settings` *(optional)* | [`DocumentLayoutJsonExportSettings`](/api/python/settings/vision/advanced/document-layout-json-export-settings/) | Settings controlling what to include in the JSON output. | **Returns:** `str` - The exported content as a string (JSON, Markdown, or IR Lite JSON depending on settings). --- ### extract_content_to_file ```python def extract_content_to_file(self, output_path: str) -> None ``` ```python def extract_content_to_file(self, output_path: str, settings: DocumentLayoutJsonExportSettings) -> None ``` Extracts structured content from the document and writes it to a file. The pipeline used is determined by the `Engine` setting and the output format by `OutputFormat`. **Parameters:** | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `output_path` | `str` | Path to the output file. | | `settings` *(optional)* | [`DocumentLayoutJsonExportSettings`](/api/python/settings/vision/advanced/document-layout-json-export-settings/) | Settings controlling what to include in the JSON output. | --- ### extract_structured ```python def extract_structured(self, request: StructuredExtractionRequest) -> str ``` Extracts structured data from the document, shaped to the JSON Schema carried by the `request`'s `{"schema":...}` envelope. The document is first read by the extraction pipeline selected by `Engine`, then an AI model fills the schema from the recognized content. Provider, model, endpoint, and confidence reporting are driven by `AiProcessingSettings` on the document's settings. **Parameters:** | Name | Type | Description | | --------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | `request` | [`StructuredExtractionRequest`](/api/python/requests/structured-extraction-request/) | The extraction request carrying the schema envelope (required) and optional instructions. | **Returns:** `str` - A JSON string with two top-level nodes: `extraction` (the schema-shaped extracted fields) and `metadata` (per-field source locations and grounding labels). --- ### extract_structured_to_file ```python def extract_structured_to_file(self, request: StructuredExtractionRequest, output_path: str) -> None ``` Extracts structured data from the document, shaped to the JSON Schema carried by the `request`'s `{"schema":...}` envelope, and writes the JSON result to a file. See `ExtractStructured` for the result shape. **Parameters:** | Name | Type | Description | | ------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | `request` | [`StructuredExtractionRequest`](/api/python/requests/structured-extraction-request/) | The extraction request carrying the schema envelope (required) and optional instructions. | | `output_path` | `str` | Path to the output file. | --- ### warmup ```python def warmup(self) -> None ``` Preloads (warms up) all resources needed for vision processing. This downloads all model files based on the document's VisionSettings before execution. Call this to avoid download delays during ExtractContent(). --- --- ## Related pages - [Open a PDF and convert it to a Word document](/api/python.md) - [Document](/api/python/document.md) - [License](/api/python/license.md) - [Query](/api/python/query.md) - [Telemetry](/api/python/telemetry.md)