---

name: project-datamodel description: "Load, validate, persist, inspect, export, and package Kiln .kiln project data models." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Project datamodel

Use this sub-skill when the task is about Kiln project files and core data-model objects: Project, Task, TaskRun, TaskOutput, Prompt, DatasetSplit, Skill, data guides, JSON schemas, input transforms, and safe CLI export of .kiln projects.

Do not use this sub-skill to invoke model providers or run a saved task. Route provider/task execution, tools, MCP runtime, and adapter selection to task-execution-providers-tools. Route evals, fine-tunes, prompt optimization, and synthetic-data generation workflows to evals-optimization-finetuning. Route documents, extraction, vector stores, and RAG to rag-documents-data.

Load these references

1. Read data-model-and-files.md for the Python datamodel APIs, parent-child file layout, load_from_file / save_to_file / delete, readonly behavior, task-run leaf filtering, prompts, skills, dataset splits, and data guides.
2. Read schema-and-input-transforms.md before creating tasks or task runs with structured JSON input/output, or when diagnosing schema and Jinja input-transform validation errors.
3. Read cli-package-project.md for kiln_ai projects list, kiln_ai tasks list, and kiln_ai package_project workflows.
4. Read troubleshooting.md when imports, file loading, schema validation, task-run enumeration, or packaging fail.

Safe helper

Use inspect_kiln_project.py for read-only inspection of a project file and optional task:

python scripts/inspect_kiln_project.py --project-file /path/to/project.kiln
python scripts/inspect_kiln_project.py --project-file /path/to/project.kiln --task-id TASK_ID

The helper prints project/task metadata and counts without writing files or invoking providers.

Operating rules

• Prefer kiln_ai.datamodel APIs over direct JSON edits; they preserve model types, validation, parent relationships, and on-disk folder conventions.
• When creating child records, pass parent= or an explicit stable path; then call save_to_file().
• For bulk inspection, use readonly=True; for mutation, reload with readonly=False or use mutable_copy().
• Remember Task.runs() returns leaf runs only by default. Pass include_intermediate_runs=True when a full multiturn run chain or exact on-disk inventory is required.
• Treat delete() as destructive: for a model file it removes the containing model directory, not just the .kiln file.