Metadata-Version: 2.4
Name: kumoai
Version: 3.0.0b3
Summary: AI on the Modern Data Stack
Author-email: "Kumo.AI" <hello@kumo.ai>
License-Expression: Apache-2.0
Project-URL: homepage, https://kumo.ai
Project-URL: documentation, https://kumo.ai/docs
Keywords: deep-learning,graph-neural-networks,cloud-data-warehouse
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
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
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD-PARTY.txt
Requires-Dist: pandas
Requires-Dist: pyarrow>=8.0.0
Requires-Dist: requests>=2.28.2
Requires-Dist: urllib3
Requires-Dist: plotly
Requires-Dist: typing_extensions>=4.5.0
Requires-Dist: kumo-api==3.0.0b3
Requires-Dist: tqdm>=4.66.0
Requires-Dist: aiohttp>=3.10.0
Requires-Dist: pydantic>=1.10.21
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: sphinx-book-theme; extra == "doc"
Requires-Dist: sphinx-copybutton; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
Requires-Dist: graphviz; extra == "doc"
Requires-Dist: mermaid-py; extra == "doc"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: requests-mock; extra == "test"
Provides-Extra: core
Requires-Dist: kumo-core>=0.1.0.dev1; extra == "core"
Provides-Extra: snowflake
Requires-Dist: kumoai[core]; extra == "snowflake"
Requires-Dist: kumo-snowflake[sdk]>=0.1.0.dev1; extra == "snowflake"
Provides-Extra: databricks
Requires-Dist: kumoai[core]; extra == "databricks"
Requires-Dist: kumo-databricks-connector>=0.1.0.dev1; extra == "databricks"
Provides-Extra: bigquery
Requires-Dist: kumoai[core]; extra == "bigquery"
Requires-Dist: kumo-bigquery>=0.1.0.dev1; extra == "bigquery"
Provides-Extra: s3
Requires-Dist: kumoai[core]; extra == "s3"
Requires-Dist: kumo-s3>=0.1.0.dev1; extra == "s3"
Provides-Extra: gcs
Requires-Dist: kumoai[core]; extra == "gcs"
Requires-Dist: kumo-gcs>=0.1.0.dev1; extra == "gcs"
Dynamic: license-file
Dynamic: requires-dist

<p align="center">
  <img height="180" src="https://kumo-sdk-public.s3.us-west-2.amazonaws.com/kumo-logo-pink.svg" />
</p>

______________________________________________________________________

The Kumo SDK implements a pythonic interface for users to programmatically
interact with the Kumo machine learning platform
([documentation](https://kumo-ai.github.io/kumo-sdk/docs/#)).

## Installation

The Kumo SDK is available for Python 3.10 to Python 3.14. To install, simply run

```
pip install kumoai
```

That is everything needed to drive the hosted Kumo platform.

Reading a warehouse or object store in *this* process needs the in-process
backend and the plugin for that vendor, which is one extra per vendor:

```
pip install kumoai[snowflake]     # or [databricks], [bigquery], [s3], [gcs]
```

Each pulls `kumo-core` -- the local backend, and so the training stack -- and
the vendor's own distribution (`kumo-snowflake`, `kumo-databricks-connector`,
`kumo-bigquery`, `kumo-s3`, `kumo-gcs`), which carries the client libraries it
imports. Installing the distribution is what registers the vendor: `kumoai`
itself names no warehouse and no object store, and finds each through entry
points. `kumoai[snowflake]` is also what Snowflake/SPCS support needs.

## Durable local-backend snapshots in Snowflake

An in-process `LocalBackend` can keep its reconstructable working files on
local disk while checkpointing completed DiskGraph snapshots to a Snowflake
named internal stage:

```python
import kumoai as kumo
from kumo_snowflake import StageArtifactLocation, spcs_identity_create_args

# Running inside Snowpark Container Services, where the runtime mounts an
# OAuth token: the identity reads it and stores no credential. Outside a
# container, build `CreateIdentityArgs` with a key pair or a password.
identity = kumo.create_identity(spcs_identity_create_args("local-snowflake"))
kumo.set_backend(kumo.LocalBackend(storage=kumo.Storage(
    scratch="/tmp/kumo",
    artifacts=StageArtifactLocation(
        "@PROD.ML.KUMO_ARTIFACTS/local-backend",
        identity=identity,
    ),
)))
```

The stage must already exist and be fully qualified. The active Snowflake role
needs `USAGE` on its database and schema and `READ`/`WRITE` on the stage.
Constructing `LocalBackend` runs a UUID-scoped PUT/COPY/LIST/GET/REMOVE probe,
then cleans it up, so a missing or external stage and ineffective privileges
fail before source staging or ingest. Snapshots are uploaded to a temporary
prefix, verified, and committed by copying `_SUCCESS` last. A new process can
therefore restore from the stage after its local scratch directory is lost.
Snowflake `COPY FILES` limits each snapshot file to 5 GB.

The stage location makes DiskGraph snapshots durable. Predictions, task
datasets, and model bundles use a local cache below `scratch`; publish those
through an output connector when they must survive the process.

Local snapshot and job IDs are process-local. Recreate a graph and call
`graph.snapshot()` to restore an unchanged staged snapshot. Export a trained
model to a registry before restart, then discover and import it by durable
registry coordinates:

```python
models = kumo.list_published_models(registry_connector)
saved = models[0]
trainer, pquery = kumo.import_model(kumo.ModelImportConfig(
    connector=registry_connector,
    location=kumo.ModelRegistryLocation(saved.name, version=saved.version),
    graph_connector=data_connector,
))
```

Discovery returns only versions published by Kumo and includes their recorded
metadata and metrics. Tables and path-addressed artifacts have no registry;
reopen the destination named in their export configuration.

## Looking up projects

Every SDK session has one active project. You can retrieve another visible
project by its display name or immutable Kumo ID without changing that active
project:

```python
import kumoai

kumoai.init()  # Selects the canonical Default project.
fraud = kumoai.get_project("Fraud Detection")

assert kumoai.current_project().name == "Default"

# Pass the stable ID to project-scoped objects when needed.
events = kumoai.BigQueryConnector(
    name="events",
    project_id="company-data-prod",  # Google Cloud project ID
    dataset_id="events",
    kumo_project_id=fraud.id,         # Kumo project ID
)
```

Use `kumoai.set_project(fraud)` when you do want to change the active project.

## Multi-categorical string columns

For a scalar string containing several categories, set the proven delimiter
on the column. Kumo persists it in the table definition, so metadata
validation, snapshots, and training all split the values identically. Comma,
pipe, semicolon, and tab are supported.

```python
interests = kumoai.Column(
    name="interests",
    stype="multicategorical",
    dtype="string",
    multicategorical_delimiter="|",
)
```

Do not set a delimiter for native `stringlist` or `intlist` columns; their
array structure already separates categories. When metadata inference detects
a delimiter, the SDK retains the inferred value automatically.

## Google identities stay credential-free in the SDK

Administrators assign BigQuery and GCS identities to project-owning groups.
Users can inspect the safe authentication mode and pass the identity to any
number of project connectors, but private keys and workload tokens never enter
SDK code. Workload identity is preferred when the deployment enables it.

```python
identity = kumoai.get_identity("Production Google")
print(identity.config.authentication.mode)
# "workload_identity" or "service_account_key"

events = kumoai.BigQueryConnector(
    name="events",
    project_id="company-data-prod",
    dataset_id="events",
    identity=identity,
)
```

Omit `identity` to ask the server to select the only authorized identity that
can access the exact connector target. Connector constructors never accept
Google keys, source credentials, or access tokens.
