Metadata-Version: 2.4
Name: intuned-files
Version: 0.1.0
Summary: Intuned SDK for file operations (to markdown, extract tables)
Author-email: Intuned Developers <engineering@intunedhq.com>
License: Elastic License 2.0
Keywords: files,intuned,sdk
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.9
Requires-Dist: pydantic<3,>=2.0.0
Description-Content-Type: text/markdown

# intuned-files

Intuned SDK for file operations. Provides helpers for converting files to
markdown and extracting tables from files, backed by the Intuned file APIs.
Must be used within Intuned projects and requires the dependency `intuned-runtime`.

## Installation

```bash
pip install intuned-files
# intuned-runtime is required at runtime (provided by the Intuned runtime).
# intuned-browser is optional, only needed for the `download` file source.
```

## Usage

### Extract markdown

```python
from intuned_files import PdfFile, extract_markdown_from_file

markdown = await extract_markdown_from_file(PdfFile(url="https://example.com/report.pdf"))
```

### Extract tables

`extract_tables_from_file` returns each table's page number, title, and cell content.

```python
from intuned_files import PdfFile, extract_tables_from_file

tables = await extract_tables_from_file(PdfFile(url="https://example.com/report.pdf"))
```

Both functions also accept a plain dict (typed via the `*Dict` TypedDicts):

```python
from intuned_files import extract_markdown_from_file

await extract_markdown_from_file({"type": "pdf", "url": "https://example.com/report.pdf"})
```

### Extract structured data

`extract_structured_data_from_file` converts the file to markdown and then extracts data
against a schema. It requires the optional `intuned-browser` dependency (the
other operations do not); it raises a clear error at call time if it is missing.

```python
from intuned_files import extract_structured_data_from_file

data = await extract_structured_data_from_file(
    {"type": "pdf", "url": "https://example.com/invoice.pdf"},
    data_schema={
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "total": {"type": "number"},
        },
        "required": ["invoice_number", "total"],
    },
)
```

`data_schema` accepts a JSON Schema dict or a Pydantic model class.

### File sources

Provide exactly one source key on the file object: `url`, `base64`,
`buffer` (raw bytes), or `download`. The `download` source accepts the
result of `download_file` from `intuned-browser`, awaited or not:

```python
from intuned_files import extract_markdown_from_file
from intuned_browser import download_file

await extract_markdown_from_file({"type": "pdf", "download": download_file(page, trigger)})
```

### Supported file types

`PdfFile`, `ImageFile`, `SpreadsheetFile` (`.xlsx`), and `DocumentFile`
(`.docx`).

## Development

```bash
uv sync
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -m "not e2e"
```
