Getting Started

Install KynML, write your first spec, and run a training loop in under five minutes.

Installation

KynML requires Python 3.11+.

Core (training only)

git clone https://github.com/your-org/kynml
cd kynml
pip install -e ".[dev]"

The core install pulls in torch, numpy, pandas, scikit-learn, and typer. No GPU required to compile or validate specs — PyTorch is only exercised during train.

Optional extras

Extra	Installs	When you need it
`serving`	`fastapi`, `uvicorn`	`kynml.serving.generate_service`
`mcp`	`mcp>=1.0`	`python -m kynml.mcp.server`
`hf`	`datasets>=2.0`	`kynml.integrations.huggingface`
`objectstore`	`s3fs`, `pyarrow`	S3/R2/local Parquet connectors
`all`	everything above	full feature surface

pip install -e ".[all]"

Verify

python -m kynml.cli --help

Expected output:

Usage: python -m kynml.cli [OPTIONS] COMMAND [ARGS]...

  KynML: train models without boilerplate.

Commands:
  ast       Print the parsed AST for a .kyn file.
  compile   Compile a .kyn file into a Python + PyTorch script.
  train     Compile and execute a .kyn training program.
  validate  Parse and validate a .kyn file.

Your First .kyn File

Create my_model.kyn:

dataset HouseData:
    source = csv("data/housing.csv")
    target = "price"
    split = 0.8
    normalize = true

model HousePriceModel:
    input 10
    dense 64 relu
    dense 32 relu
    dense 1 linear

train:
    model = HousePriceModel
    data = HouseData
    loss = mse
    optimizer = adam(lr=0.001)
    epochs = 20
    batch = 32
    device = auto

evaluate:
    metrics = [mae, rmse]

export:
    format = torch
    path = "models/house_price.pt"

KynML syntax rules:
- Top-level blocks (dataset, model, train, evaluate, export) start at column 1.
- Body lines are indented by exactly 4 spaces — no tabs.
- Lines starting with # are comments and are stripped before parsing.
- Named blocks (dataset, model) take a name: dataset HouseData:.
- Simple blocks (train, evaluate, export) have no name: train:.

Validate

Check syntax and semantics without touching disk or PyTorch:

python -m kynml.cli validate my_model.kyn

On success:

Valid KynML program: my_model.kyn

On error, a precise location is printed:

KynMLError: my_model.kyn:7: Unsupported activation 'elu' in model 'HousePriceModel'

Exit code 0 = valid, 1 = error.

Compile

Transpile the spec to a standalone Python + PyTorch script:

python -m kynml.cli compile my_model.kyn --out generated/my_model.py

This runs parse → semantic validation → codegen. The compile pipeline is pure Python — no GPU, no torch import at compile time. The generated script is self-contained and runnable independently of KynML.

Output:

Generated generated/my_model.py

Train

Compile and immediately execute:

python -m kynml.cli train my_model.kyn

KynML writes the script to generated/<stem>.py, then calls the current Python interpreter on it. Epoch logs are streamed to stdout:

Epoch 1/20 - loss: 0.8421
Epoch 2/20 - loss: 0.6103
...
mae: 0.1234
rmse: 0.1876
Saved model to /path/to/models/house_price.pt

Reading the Generated Code

The generated script at generated/my_model.py is a flat, readable Python file. Key sections:

Section	What it does
Constants block (`DATASET_PATH`, `EPOCHS`, …)	All spec values surfaced as module-level vars; easy to override for quick experiments
`load_dataset()`	Reads CSV, one-hot encodes categoricals, splits, optionally normalises with `StandardScaler`
`class HousePriceModel(nn.Module)`	The model as a `nn.Sequential` wrapped in a named class
`build_criterion()`	Returns the loss function
`build_optimizer(model)`	Returns the configured optimizer
`build_scheduler(optimizer)`	Returns the LR scheduler, or `None` if none specified
`train_model(...)`	Full training loop with optional AMP, early stopping, checkpointing
`evaluate_model(...)`	Computes requested metrics on the test split
`export_model(model)`	Saves the model in the requested format
`main()`	Wires everything together

Edit the generated file freely for one-off experiments. For repeatable changes, edit the .kyn spec and recompile.

Where Models Go

By default, the kynml train command writes the compiled script to:

generated/<your_spec_stem>.py

Trained model artifacts land wherever export.path points in your spec, resolved relative to the current working directory at compile time. For example:

export:
    format = torch
    path = "models/house_price.pt"

Running python -m kynml.cli train my_model.kyn from /projects/demo writes the model to /projects/demo/models/house_price.pt, creating parent directories as needed.

Next Steps

Language Reference — every keyword, option, and allowed value
CLI Reference — full flag documentation
Tutorial: Regression — a complete worked example