Metadata-Version: 2.4
Name: graphon-client
Version: 0.15.0
Summary: A Python client library for the Graphon API - Build graphs from your files
Author-email: Arbaaz Khan <arbaaz@graphon.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/arbaazkhan2/graphon-client
Project-URL: Bug Reports, https://github.com/arbaazkhan2/graphon-client/issues
Project-URL: Source, https://github.com/arbaazkhan2/graphon-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx==0.28.1
Provides-Extra: e2e
Requires-Dist: google-cloud-storage==3.4.0; extra == "e2e"
Dynamic: license-file

# Graphon Client

A Python client library for the Graphon API - Build unified graphs from your files.
See https://app.graphon.ai/docs .

## Attaching metadata to files

Files can carry user-provided metadata, supplied as a list of segments. For
documents `start`/`end` are page numbers (integers); for video/audio they are
seconds (a closed range, `start <= end`). `attributes` is a map of scalar or
scalar-list values. The client does no validation — the server validates and may
reject metadata that exceeds its limits (max 2 MiB total, 10000 segments, 64
attributes per segment, key length 128, value length 4096, and 256 entries per
list value).

Metadata can be passed as `FileMetadata`/`FileMetadataSegment` objects or as a
raw `{"segments": [...]}` dict.

```python
from graphon_client import FileMetadata, FileMetadataSegment, FileUpload

metadata = FileMetadata(
    segments=[
        FileMetadataSegment(
            start=1,
            end=3,
            attributes={"chapter": "Intro", "tags": ["overview", "setup"]},
        ),
    ],
)

# Pass FileUpload specs instead of file_paths to attach per-file metadata.
group_id = await client.upload_process_and_create_group(
    files=[FileUpload(path="manual.pdf", metadata=metadata)],
    group_name="My Graph",
)
```

`files=` is accepted by both `upload_and_process_files` and
`upload_process_and_create_group` as an alternative to `file_paths=`. The two are
mutually exclusive — passing both raises `ValueError`. Existing `file_paths=`
callers are unaffected.

## Submitting a file by URL

`submit_from_url` ingests a file from an `https://` or `gs://` URL — the server
downloads and processes it. It returns a `file_id`; poll for completion with
`poll_file_until_complete`.

```python
file_id = await client.submit_from_url(
    source_url="https://example.com/report.pdf",
    file_name="report.pdf",
    file_type="document",
    file_metadata=metadata,  # optional
)
detail = await client.poll_file_until_complete(file_id)
```

## Exported types

`GraphonClient`, `FileObject`, `FileDetail`, `GroupDetail`, `GroupListItem`,
`GroupModifyResult`, `SkippedFile`, `QueryResponse`, `QueryResponseLegacy`,
`FileMetadata`, `FileMetadataSegment`, `FileUpload`.
