| Name | kiln-ai JSON |
| Version |
0.7.1
JSON |
| download |
| home_page | None |
| Summary | Kiln AI |
| upload_time | 2024-12-15 17:57:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# Kiln AI Core Library
<p align="center">
<picture>
<img width="205" alt="Kiln AI Logo" src="https://github.com/user-attachments/assets/5fbcbdf7-1feb-45c9-bd73-99a46dd0a47f">
</picture>
</p>
[](https://pypi.org/project/kiln-ai)
[](https://pypi.org/project/kiln-ai)
[](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html)
---
## Installation
```console
pip install kiln_ai
```
## About
This package is the Kiln AI core library. There is also a separate desktop application and server package. Learn more about Kiln AI at [getkiln.ai](https://getkiln.ai) and on Github: [github.com/Kiln-AI/kiln](https://github.com/Kiln-AI/kiln).
# Guide: Using the Kiln Python Library
In this guide we'll walk common examples of how to use the library.
## Documentation
The library has a [comprehensive set of docs](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html).
## Table of Contents
- [Using the Kiln Data Model](#using-the-kiln-data-model)
- [Understanding the Kiln Data Model](#understanding-the-kiln-data-model)
- [Datamodel Overview](#datamodel-overview)
- [Load a Project](#load-a-project)
- [Load an Existing Dataset into a Kiln Task Dataset](#load-an-existing-dataset-into-a-kiln-task-dataset)
- [Using your Kiln Dataset in a Notebook or Project](#using-your-kiln-dataset-in-a-notebook-or-project)
- [Using Kiln Dataset in Pandas](#using-kiln-dataset-in-pandas)
- [Advanced Usage](#advanced-usage)
## Installation
```bash
pip install kiln-ai
```
## Using the Kiln Data Model
### Understanding the Kiln Data Model
Kiln projects are simply a directory of files (mostly JSON files with the extension `.kiln`) that describe your project, including tasks, runs, and other data.
This dataset design was chosen for several reasons:
- Git compatibility: Kiln project folders are easy to collaborate on in git. The filenames use unique IDs to avoid conflicts and allow many people to work in parallel. The files are small and easy to compare using standard diff tools.
- JSON allows you to easily load and manipulate the data using standard tools (pandas, polars, etc)
The Kiln Python library provides a set of Python classes that which help you easily interact with your Kiln dataset. Using the library to load and manipulate your dataset is the fastest way to get started, and will guarantees you don't insert any invalid data into your dataset. There's extensive validation when using the library, so we recommend using it to load and manipulate your dataset over direct JSON manipulation.
### Datamodel Overview
- Project: a Kiln Project that organizes related tasks
- Task: a specific task including prompt instructions, input/output schemas, and requirements
- TaskRun: a sample (run) of a task including input, output and human rating information
- DatasetSplit: a frozen collection of task runs divided into train/test/validation splits
- Finetune: configuration and status tracking for fine-tuning models on task data
### Load a Project
Assuming you've created a project in the Kiln UI, you'll have a `project.kiln` file in your `~/Kiln Projects/Project Name` directory.
```python
from kiln_ai.datamodel import Project
project = Project.load_from_file("path/to/your/project.kiln")
print("Project: ", project.name, " - ", project.description)
# List all tasks in the project, and their dataset sizes
tasks = project.tasks()
for task in tasks:
print("Task: ", task.name, " - ", task.description)
print("Total dataset size:", len(task.runs()))
```
### Load an Existing Dataset into a Kiln Task Dataset
If you already have a dataset in a file, you can load it into a Kiln project.
**Important**: Kiln will validate the input and output schemas, and ensure that each datapoint in the dataset is valid for this task.
- Plaintext input/output: ensure "output_json_schema" and "input_json_schema" not set in your Task definition.
- JSON input/output: ensure "output_json_schema" and "input_json_schema" are valid JSON schemas in your Task definition. Every datapoint in the dataset must be valid JSON fitting the schema.
Here's a simple example of how to load a dataset into a Kiln task:
```python
import kiln_ai
import kiln_ai.datamodel
# Created a project and task via the UI and put its path here
task_path = "/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln"
task = kiln_ai.datamodel.Task.load_from_file(task_path)
# Add data to the task - loop over you dataset and run this for each item
item = kiln_ai.datamodel.TaskRun(
parent=task,
input='{"topic": "AI"}',
output=kiln_ai.datamodel.TaskOutput(
output='{"setup": "What is AI?", "punchline": "content_here"}',
),
)
item.save_to_file()
print("Saved item to file: ", item.path)
```
And here's a more complex example of how to load a dataset into a Kiln task. This example sets the source of the data (human in this case, but you can also set it be be synthetic), the created_by property, and a 5-star rating.
```python
import kiln_ai
import kiln_ai.datamodel
# Created a project and task via the UI and put its path here
task_path = "/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln"
task = kiln_ai.datamodel.Task.load_from_file(task_path)
# Add data to the task - loop over you dataset and run this for each item
item = kiln_ai.datamodel.TaskRun(
parent=task,
input='{"topic": "AI"}',
input_source=kiln_ai.datamodel.DataSource(
type=kiln_ai.datamodel.DataSourceType.human,
properties={"created_by": "John Doe"},
),
output=kiln_ai.datamodel.TaskOutput(
output='{"setup": "What is AI?", "punchline": "content_here"}',
source=kiln_ai.datamodel.DataSource(
type=kiln_ai.datamodel.DataSourceType.human,
properties={"created_by": "Jane Doe"},
),
rating=kiln_ai.datamodel.TaskOutputRating(score=5,type="five_star"),
),
)
item.save_to_file()
print("Saved item to file: ", item.path)
```
### Using your Kiln Dataset in a Notebook or Project
You can use your Kiln dataset in a notebook or project by loading the dataset into a pandas dataframe.
```python
import kiln_ai
import kiln_ai.datamodel
# Created a project and task via the UI and put its path here
task_path = "/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln"
task = kiln_ai.datamodel.Task.load_from_file(task_path)
runs = task.runs()
for run in runs:
print(f"Input: {run.input}")
print(f"Output: {run.output.output}")
print(f"Total runs: {len(runs)}")
```
### Using Kiln Dataset in Pandas
You can also use your Kiln dataset in a pandas dataframe, or a similar script for other tools like polars.
```python
import glob
import json
import pandas as pd
from pathlib import Path
task_dir = "/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator"
dataitem_glob = task_dir + "/runs/*/task_run.kiln"
dfs = []
for file in glob.glob(dataitem_glob):
js = json.loads(Path(file).read_text())
df = pd.DataFrame([{
"input": js["input"],
"output": js["output"]["output"],
}])
# Alternatively: you can use pd.json_normalize(js) to get the full json structure
# df = pd.json_normalize(js)
dfs.append(df)
final_df = pd.concat(dfs, ignore_index=True)
print(final_df)
```
### Advanced Usage
The library can do a lot more than the examples we've shown here.
See the [docs](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html) for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "kiln-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "\"Steve Cosman, Chesterfield Laboratories Inc\" <scosman@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/43/24/a3b80a0e985e6d7be2e096f8cbd4673a3c3c5afae26c149b916e171be721/kiln_ai-0.7.1.tar.gz",
"platform": null,
"description": "# Kiln AI Core Library\n\n<p align=\"center\">\n <picture>\n <img width=\"205\" alt=\"Kiln AI Logo\" src=\"https://github.com/user-attachments/assets/5fbcbdf7-1feb-45c9-bd73-99a46dd0a47f\">\n </picture>\n</p>\n\n[](https://pypi.org/project/kiln-ai)\n[](https://pypi.org/project/kiln-ai)\n[](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html)\n\n---\n\n## Installation\n\n```console\npip install kiln_ai\n```\n\n## About\n\nThis package is the Kiln AI core library. There is also a separate desktop application and server package. Learn more about Kiln AI at [getkiln.ai](https://getkiln.ai) and on Github: [github.com/Kiln-AI/kiln](https://github.com/Kiln-AI/kiln).\n\n# Guide: Using the Kiln Python Library\n\nIn this guide we'll walk common examples of how to use the library.\n\n## Documentation\n\nThe library has a [comprehensive set of docs](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html).\n\n## Table of Contents\n\n- [Using the Kiln Data Model](#using-the-kiln-data-model)\n - [Understanding the Kiln Data Model](#understanding-the-kiln-data-model)\n - [Datamodel Overview](#datamodel-overview)\n - [Load a Project](#load-a-project)\n - [Load an Existing Dataset into a Kiln Task Dataset](#load-an-existing-dataset-into-a-kiln-task-dataset)\n - [Using your Kiln Dataset in a Notebook or Project](#using-your-kiln-dataset-in-a-notebook-or-project)\n - [Using Kiln Dataset in Pandas](#using-kiln-dataset-in-pandas)\n- [Advanced Usage](#advanced-usage)\n\n## Installation\n\n```bash\npip install kiln-ai\n```\n\n## Using the Kiln Data Model\n\n### Understanding the Kiln Data Model\n\nKiln projects are simply a directory of files (mostly JSON files with the extension `.kiln`) that describe your project, including tasks, runs, and other data.\n\nThis dataset design was chosen for several reasons:\n\n- Git compatibility: Kiln project folders are easy to collaborate on in git. The filenames use unique IDs to avoid conflicts and allow many people to work in parallel. The files are small and easy to compare using standard diff tools.\n- JSON allows you to easily load and manipulate the data using standard tools (pandas, polars, etc)\n\nThe Kiln Python library provides a set of Python classes that which help you easily interact with your Kiln dataset. Using the library to load and manipulate your dataset is the fastest way to get started, and will guarantees you don't insert any invalid data into your dataset. There's extensive validation when using the library, so we recommend using it to load and manipulate your dataset over direct JSON manipulation.\n\n### Datamodel Overview\n\n- Project: a Kiln Project that organizes related tasks\n - Task: a specific task including prompt instructions, input/output schemas, and requirements\n - TaskRun: a sample (run) of a task including input, output and human rating information\n - DatasetSplit: a frozen collection of task runs divided into train/test/validation splits\n - Finetune: configuration and status tracking for fine-tuning models on task data\n\n### Load a Project\n\nAssuming you've created a project in the Kiln UI, you'll have a `project.kiln` file in your `~/Kiln Projects/Project Name` directory.\n\n```python\nfrom kiln_ai.datamodel import Project\n\nproject = Project.load_from_file(\"path/to/your/project.kiln\")\nprint(\"Project: \", project.name, \" - \", project.description)\n\n# List all tasks in the project, and their dataset sizes\ntasks = project.tasks()\nfor task in tasks:\n print(\"Task: \", task.name, \" - \", task.description)\n print(\"Total dataset size:\", len(task.runs()))\n```\n\n### Load an Existing Dataset into a Kiln Task Dataset\n\nIf you already have a dataset in a file, you can load it into a Kiln project.\n\n**Important**: Kiln will validate the input and output schemas, and ensure that each datapoint in the dataset is valid for this task.\n\n- Plaintext input/output: ensure \"output_json_schema\" and \"input_json_schema\" not set in your Task definition.\n- JSON input/output: ensure \"output_json_schema\" and \"input_json_schema\" are valid JSON schemas in your Task definition. Every datapoint in the dataset must be valid JSON fitting the schema.\n\nHere's a simple example of how to load a dataset into a Kiln task:\n\n```python\n\nimport kiln_ai\nimport kiln_ai.datamodel\n\n# Created a project and task via the UI and put its path here\ntask_path = \"/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln\"\ntask = kiln_ai.datamodel.Task.load_from_file(task_path)\n\n# Add data to the task - loop over you dataset and run this for each item\nitem = kiln_ai.datamodel.TaskRun(\n parent=task,\n input='{\"topic\": \"AI\"}',\n output=kiln_ai.datamodel.TaskOutput(\n output='{\"setup\": \"What is AI?\", \"punchline\": \"content_here\"}',\n ),\n)\nitem.save_to_file()\nprint(\"Saved item to file: \", item.path)\n```\n\nAnd here's a more complex example of how to load a dataset into a Kiln task. This example sets the source of the data (human in this case, but you can also set it be be synthetic), the created_by property, and a 5-star rating.\n\n```python\nimport kiln_ai\nimport kiln_ai.datamodel\n\n# Created a project and task via the UI and put its path here\ntask_path = \"/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln\"\ntask = kiln_ai.datamodel.Task.load_from_file(task_path)\n\n# Add data to the task - loop over you dataset and run this for each item\nitem = kiln_ai.datamodel.TaskRun(\n parent=task,\n input='{\"topic\": \"AI\"}',\n input_source=kiln_ai.datamodel.DataSource(\n type=kiln_ai.datamodel.DataSourceType.human,\n properties={\"created_by\": \"John Doe\"},\n ),\n output=kiln_ai.datamodel.TaskOutput(\n output='{\"setup\": \"What is AI?\", \"punchline\": \"content_here\"}',\n source=kiln_ai.datamodel.DataSource(\n type=kiln_ai.datamodel.DataSourceType.human,\n properties={\"created_by\": \"Jane Doe\"},\n ),\n rating=kiln_ai.datamodel.TaskOutputRating(score=5,type=\"five_star\"),\n ),\n)\nitem.save_to_file()\nprint(\"Saved item to file: \", item.path)\n```\n\n### Using your Kiln Dataset in a Notebook or Project\n\nYou can use your Kiln dataset in a notebook or project by loading the dataset into a pandas dataframe.\n\n```python\nimport kiln_ai\nimport kiln_ai.datamodel\n\n# Created a project and task via the UI and put its path here\ntask_path = \"/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator/task.kiln\"\ntask = kiln_ai.datamodel.Task.load_from_file(task_path)\n\nruns = task.runs()\nfor run in runs:\n print(f\"Input: {run.input}\")\n print(f\"Output: {run.output.output}\")\n\nprint(f\"Total runs: {len(runs)}\")\n```\n\n### Using Kiln Dataset in Pandas\n\nYou can also use your Kiln dataset in a pandas dataframe, or a similar script for other tools like polars.\n\n```python\nimport glob\nimport json\nimport pandas as pd\nfrom pathlib import Path\n\ntask_dir = \"/Users/youruser/Kiln Projects/test project/tasks/632780983478 - Joke Generator\"\ndataitem_glob = task_dir + \"/runs/*/task_run.kiln\"\n\ndfs = []\nfor file in glob.glob(dataitem_glob):\n js = json.loads(Path(file).read_text())\n\n df = pd.DataFrame([{\n \"input\": js[\"input\"],\n \"output\": js[\"output\"][\"output\"],\n }])\n\n # Alternatively: you can use pd.json_normalize(js) to get the full json structure\n # df = pd.json_normalize(js)\n dfs.append(df)\nfinal_df = pd.concat(dfs, ignore_index=True)\nprint(final_df)\n```\n\n### Advanced Usage\n\nThe library can do a lot more than the examples we've shown here.\n\nSee the [docs](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html) for more information.\n",
"bugtrack_url": null,
"license": null,
"summary": "Kiln AI",
"version": "0.7.1",
"project_urls": {
"Documentation": "https://kiln-ai.github.io/Kiln/kiln_core_docs/kiln_ai.html",
"Homepage": "https://getkiln.ai",
"Issues": "https://github.com/Kiln-AI/kiln/issues",
"Repository": "https://github.com/Kiln-AI/kiln"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1ca18cecd8e9295f0fd456971115fa64ff498c87374d7c954750e5614d02c13a",
"md5": "b3e6fd9d3b40d8f2c37b06e09f004a47",
"sha256": "10302ba85eeff5582ab6c0a1f05af67f3102f915c24e27aeb147f320406ab458"
},
"downloads": -1,
"filename": "kiln_ai-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b3e6fd9d3b40d8f2c37b06e09f004a47",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 107211,
"upload_time": "2024-12-15T17:57:03",
"upload_time_iso_8601": "2024-12-15T17:57:03.662668Z",
"url": "https://files.pythonhosted.org/packages/1c/a1/8cecd8e9295f0fd456971115fa64ff498c87374d7c954750e5614d02c13a/kiln_ai-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4324a3b80a0e985e6d7be2e096f8cbd4673a3c3c5afae26c149b916e171be721",
"md5": "2f5c637a600d625d590eda0ff18db999",
"sha256": "c6ab87e593e39afa4cfeaf0f6d15c6129ab7fd514f0cc12313ad057e692d5a71"
},
"downloads": -1,
"filename": "kiln_ai-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "2f5c637a600d625d590eda0ff18db999",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1075527,
"upload_time": "2024-12-15T17:57:06",
"upload_time_iso_8601": "2024-12-15T17:57:06.231261Z",
"url": "https://files.pythonhosted.org/packages/43/24/a3b80a0e985e6d7be2e096f8cbd4673a3c3c5afae26c149b916e171be721/kiln_ai-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 17:57:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kiln-AI",
"github_project": "kiln",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "kiln-ai"
}
