kumoai-reference

# KumoAI Reference Skill **Load this skill only after a request has passed all checks in `kumo-data-science/SKILL.md`.** This skill provides reference docs for translating a validated, structured ML request into KumoAI graph configuration, PQL, and KumoSDK code. --- ## What's in this skill | Document | Purpose | |---|---| | `kumoai-reference/references/graph_construction.md` | How to map tables → Kumo nodes and edges | | `kumoai-reference/references/pql_writing.md` | Writing Prediction Query Language for the validated task | | `kumoai-reference/references/kumo_finetuning_sdk.md` | Kumo Predict SDK API and version-matched code generation | | `kumoai-reference/references/troubleshooting_signals.md` | Known errors at graph/PQL generation time | --- ## Provenance of every claim **The published Kumo documentation is out of date for this version of the local SDK and is not a source here.** Do not cite it, link to it, fetch it, or reconcile against it. If a claim in these files has no `Source:` line, treat it as unverified and say so rather than filling the gap from the public docs or from memory. Every claim that is grounded carries: - ``Source: shipped package (`<python.module.path>`)`` — verified against the source of the shipped Kumo package, at the named module. This is the only authoritative kind of source. Anything else is marked inline as **Not verified**. When you hit one, ask the user rather than guessing. ## Before anything: one API, one package There is a single Kumo SDK, verified against the shipped package named in `kumoai-reference/references/kumo_finetuning_sdk.md` §0. Older material describing two interchangeable "variants" was a misreading of one SDK before and after a rename. If a user's code contains `set_backend`, `LocalBackend`, `create_identity`, `OutputConfig`, `kumo.Stype`, or edges written as dicts, it targets a **superseded** build: say so and rewrite it rather than copying its shape. See `kumoai-reference/references/kumo_finetuning_sdk.md` §11.1. Connection, in this order: `SnowflakeConnector.from_spcs_env()` when `SPCS_TOKEN_PATH` exists, else `.from_connection_toml()`, else a `SnowflakeIdentity` from Snowflake secrets attached to the notebook (`kumoai-reference/references/kumo_finetuning_sdk.md` §3). None needs a key in code. ## Execution flow Given the validated structured payload from `kumo-data-science/SKILL.md`: ### Step 1 — Graph construction Reference `kumoai-reference/references/graph_construction.md`. Map each table in the payload: - Every source table → a `kumo.Table` with typed columns, a primary key where one was confirmed, and a time column where one exists - Link the tables into a `kumo.Graph` by declaring edges between matching key columns - Specify join keys, timestamp columns, and any column-level annotations. ### Step 2 — PQL query Reference `kumoai-reference/references/pql_writing.md`. Translate the prediction target into a PQL `predict` statement: - Entity to predict on - Label definition - Prediction horizon - Feature tables to include ### Step 3 — SDK code generation Reference `kumoai-reference/references/kumo_finetuning_sdk.md`. Generate: - `kumo.Graph` definition - `kumo.PredictiveQuery` and `kumo.Trainer` configuration - `graph.snapshot()`, then `generate_training_table` / `generate_prediction_table` - `Trainer.fit(training_table, snapshot=snapshot)` and `Trainer.predict(prediction_table, snapshot=snapshot, output_config=...)` — **`snapshot=` is required on both** - `kumo.PredictionOutputConfig(connector=, artifact_type=, table_name=, write_mode=)` built from the output destination in the validated payload Emit only signatures that appear in `kumoai-reference/references/kumo_finetuning_sdk.md`. Do not infer or invent them. ### Step 4 — Sanity check Before returning code: - Confirm that the selected column lists enforce every exclusion confirmed at the graph gate. The target column always stays selected — the query references it by name. Re-check that no feature is determined after its table's row time, and that no non-target feature is derived from the prediction target. Do not return code that omits `column_names` for a table that has exclusions. - If the active host adapter restricts a semantic type, confirm the generated code includes the adapter's runtime type guard before `graph.snapshot()`. - Confirm that the output table in the generated code matches the output location from the original request. - Check against known error patterns in `kumoai-reference/references/troubleshooting_signals.md`. --- ## Scope boundary This skill generates code. It does not: - Run jobs or check job status - Interpret evaluation metrics or model outputs - Repair runtime errors — recognise known signals with `kumoai-reference/references/troubleshooting_signals.md`, report them, and stop