K kynetra.dev / KynML
Docs Getting Started

Getting Started

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

Installation

KynML requires Python 3.11+.

Core compiler and local training

git clone https://github.com/hyperbridgedigital/kynml
cd kynml
pip install -e ".[dev,data,train]"

The core kynml install contains the parser, semantic checker, IR, code
generators, and CLI with only Typer as a required dependency. The development
command above adds concrete data checks and local training. No GPU is required
to compile or validate specs.

Optional extras

Extra Installs When you need it
data numpy, pandas Concrete CSV schema/data checks
train torch, numpy, pandas, scikit-learn Local training and sweeps
serve fastapi, uvicorn + training runtime kynml.serving.generate_service
mcp mcp>=1.0 python -m kynml.mcp.server
hf datasets, pandas kynml.integrations.huggingface
objectstore s3fs, pyarrow, pandas 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.
  compare   Show checked-in adjacent-tool positioning.
  compile   Compile a .kyn file into a Python + PyTorch script.
  fmt       Format .kyn source in canonical form.
  lsp       Start the language server over stdio.
  schema    Validate a concrete dataset/model contract.
  sweep     Expand and run parameter combinations.
  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