Keys & Caches Basics

Command Formats

Keys & Caches supports two command formats to fit different workflows:

1. Interactive Mode (Beginner-Friendly)

kandc python my_model.py --epochs 10 --batch-size 32

How it works:

Kandc prompts you step-by-step for job configuration
You'll be asked to choose GPU type, app name, requirements file, etc.
Great for getting started and one-off experiments
No kandc flags allowed - everything is configured through prompts

2. Non-Interactive Mode (Automation-Ready)

kandc --app-name "my-experiment" --gpu 3 -- python my_model.py --epochs 10

How it works:

All configuration specified via command line flags before the -- separator
No prompts - runs immediately with provided settings
Perfect for scripts, CI/CD, and automation
Everything after -- is your Python command and its arguments

Key difference: Interactive mode asks you questions, non-interactive mode uses flags you provide upfront.

Essential Configuration

Common Flags

--app-name "my-job"
- Job name for tracking
--gpu <type>
- GPU types (enum: 4, 2, 8, 1)
--upload-dir .
- Directory to upload (default: current)
--requirements requirements.txt
- Python dependencies

Requirements Files

Create a

requirements.txt

for your dependencies:

torch>=2.0.0
torchvision
numpy
matplotlib
transformers  # if using HuggingFace models

Model Profiling

Keys & Caches automatically profiles your models to help you understand performance. There are two ways to enable profiling:

`capture_model_class`
- For Your Own Models

Use this decorator when defining your own PyTorch model classes:

from kandc import capture_model_class
import torch.nn as nn

@capture_model_class(model_name="MyCustomModel")
class MyModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.layers = nn.Sequential(
            nn.Linear(784, 256),
            nn.ReLU(),
            nn.Linear(256, 10)
        )
    
    def forward(self, x):
        return self.layers(x)

When to use:

You're defining your own model classes
You want profiling built-in from the start
Most common approach for custom models

`capture_model_instance`
- For Pre-Built Models

Use this function to wrap existing model instances:

from kandc import capture_model_instance
from transformers import AutoModel

# Load a pre-trained model
model = AutoModel.from_pretrained("bert-base-uncased")

# Wrap it for profiling
model = capture_model_instance(model, model_name="BERT")

When to use:

Working with pre-trained models (HuggingFace, torchvision, etc.)
You can't modify the original class definition
Need to add profiling to existing model instances

What You Get From Profiling

Layer-level timing - See which layers are bottlenecks
Memory tracking - Monitor GPU memory usage per layer
Shape recording - Debug tensor dimension issues
Chrome traces - Visual timeline viewable in chrome://tracing
JSON files - Detailed profiling data saved automatically

Excluding Files with
`.kandcignore`

When you run kandc, it uploads your entire project directory to the cloud. To avoid uploading large or unnecessary files, create a

.kandcignore

file in your project root:

# Large model files (download them in your script instead)
*.bin
*.safetensors
*.ckpt
*.pth

# Data directories (use cloud storage or download in script)
data/
datasets/
checkpoints/
models/

# Logging and experiment tracking
wandb/
mlruns/
logs/

# Development files
.git/
__pycache__/
.pytest_cache/
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

Why exclude files:

Faster uploads - Only essential code gets uploaded
Lower costs - Less data transfer and storage
Security - Avoid uploading sensitive files or credentials

Best practice: Instead of uploading large files, download them in your script:

# Instead of uploading a 5GB model file, download it in the cloud:
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-large-uncased")  # Downloads automatically

Documentation