Merge pull request #370 from Kiln-AI/main

Update docs for v0.17 release

Author: scosman

.cursorrules

@@ -7,5 +7,6 @@
    2) assume an appriopirate test file already exists, find it, and suggest tests get appended to that file. If no such file exists, ask me before assuming a new test file is the correct route.
    3) Test brevity is important. Use approaches for re-use and brevity including using fixtures for repeated code, and using pytest parameterize for similar tests
    4) After writing a new test, run it and ensure it works. Fix any issues you find.
-
- 
+ - To run web tests `cd app/web_ui` then `npm run test_run`
+ - Don't include comments in code explaining changes, explain changes in chat instead.
+ - If a python API's interface changes (or a new one is added), generate new bindings by running `cd app/web_ui/src/lib/ && ./generate.sh`

.vscode/settings.json

@@ -15,6 +15,10 @@
   ],
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.autoImportCompletions": true,
+  "python.analysis.extraPaths": ["./"],
+  "python.analysis.ignore": ["**/test_*.py"],
   "files.exclude": {
     "**/__pycache__": true,
     "**/.pytest_cache": true,

AGENTS.md

@@ -0,0 +1,32 @@
+## .cursorrules
+
+Read .cursorrules before starting.
+
+## Python testing, formatting and linting
+
+If you've edited any python code, the following commands should run and not produce error codes. Fix any issues and re-run.
+
+```
+# Formatting 1:
+uvx  ruff check --select I
+# Formatting 2:
+uvx ruff format --check .
+# type checking: warnings in output are acceptable, but error codes are not
+uv run pyright .
+# tests:
+uv run python3 -m pytest --benchmark-quiet -q .
+```
+
+## Web app testing, formatting and linting
+
+If you change any web app code, the following commands should run and not produce error codes. Fix any issues and re-run.
+
+```
+# All commands below should be run from app/web_ui directory
+cd app/web_ui
+npm run format_check
+npm run lint
+npm run check
+npm run test_run
+npm run build > /dev/null
+```

CONTRIBUTING.md

@@ -26,7 +26,7 @@ Running the web-UI and Python servers separately is useful for development, as b
 
 To run the API server, Studio server, and Studio Web UI with auto-reload for development:
 
-1. In your first terminal:
+1. In your first terminal, navigate to the base Kiln directory:
 
    ```bash
    uv run python -m app.desktop.dev_server
@@ -54,7 +54,7 @@ Please ensure any new code has test coverage, and that all code is formatted and
 To confirm everything works locally, run:
 
 ```bash
-./checks.sh
+uv run ./checks.sh
 ```
 
 ## Optional Setup
@@ -71,7 +71,6 @@ We suggest the following extensions for VSCode/Cursor. With them, you'll get com
 - Svelte for VS Code
 - Vitest
 - ESLint
-- Cursor Pyright
 
 ### llms.txt
 

README.md

@@ -22,10 +22,10 @@
 | CI      | [![Build and Test](https://github.com/Kiln-AI/kiln/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/Kiln-AI/kiln/actions/workflows/build_and_test.yml) [![Format and Lint](https://github.com/Kiln-AI/kiln/actions/workflows/format_and_lint.yml/badge.svg)](https://github.com/Kiln-AI/kiln/actions/workflows/format_and_lint.yml) [![Desktop Apps Build](https://github.com/Kiln-AI/kiln/actions/workflows/build_desktop.yml/badge.svg)](https://github.com/Kiln-AI/kiln/actions/workflows/build_desktop.yml) [![Web UI Build](https://github.com/Kiln-AI/kiln/actions/workflows/web_format_lint_build.yml/badge.svg)](https://github.com/Kiln-AI/kiln/actions/workflows/web_format_lint_build.yml) [![Test Count Badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/scosman/57742c1b1b60d597a6aba5d5148d728e/raw/test_count_kiln.json)](https://github.com/Kiln-AI/kiln/actions/workflows/test_count.yml) [![Test Coverage Badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/scosman/57742c1b1b60d597a6aba5d5148d728e/raw/library_coverage_kiln.json)](https://github.com/Kiln-AI/kiln/actions/workflows/test_count.yml) [![Docs](https://github.com/Kiln-AI/Kiln/actions/workflows/build_docs.yml/badge.svg)](https://github.com/Kiln-AI/Kiln/actions/workflows/build_docs.yml) |
 | Package | [![PyPI - Version](https://img.shields.io/pypi/v/kiln-ai.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/kiln-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kiln-ai.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/kiln-ai/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Meta    | [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![types - Pyright](https://img.shields.io/badge/types-pyright-blue.svg)](https://github.com/microsoft/pyright) [![Docs](https://img.shields.io/badge/docs-pdoc-blue)](https://kiln-ai.github.io/Kiln/kiln_core_docs/index.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Apps    | [![MacOS](https://img.shields.io/badge/MacOS-black?logo=apple)](https://github.com/Kiln-AI/Kiln/releases/latest) [![Windows](https://img.shields.io/badge/Windows-0067b8.svg?logo=data:image/svg%2bxml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMzIgMzIiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE2Ljc0MiAxNi43NDJ2MTQuMjUzaDE0LjI1M3YtMTQuMjUzek0xLjAwNCAxNi43NDJ2MTQuMjUzaDE0LjI1NnYtMTQuMjUzek0xNi43NDIgMS4wMDR2MTQuMjU2aDE0LjI1M3YtMTQuMjU2ek0xLjAwNCAxLjAwNHYxNC4yNTZoMTQuMjU2di0xNC4yNTZ6Ij48L3BhdGg+Cjwvc3ZnPg==)](https://github.com/Kiln-AI/Kiln/releases/latest) [![Linux](https://img.shields.io/badge/Linux-444444?logo=linux&logoColor=ffffff)](https://github.com/Kiln-AI/Kiln/releases/latest) ![Github Downsloads](https://img.shields.io/github/downloads/kiln-ai/kiln/total)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Connect | [![Discord](https://img.shields.io/badge/Discord-Kiln_AI-blue?logo=Discord&logoColor=white)](https://discord.gg/Q5QwFeGTDh) [![Newsletter](https://img.shields.io/badge/Newsletter-kilnai-blue?logo=Substack&logoColor=white)](https://kilnai.substack.com)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Apps    | [![MacOS](https://img.shields.io/badge/MacOS-black?logo=apple)](https://getkiln.ai/download) [![Windows](https://img.shields.io/badge/Windows-0067b8.svg?logo=data:image/svg%2bxml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMzIgMzIiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE2Ljc0MiAxNi43NDJ2MTQuMjUzaDE0LjI1M3YtMTQuMjUzek0xLjAwNCAxNi43NDJ2MTQuMjUzaDE0LjI1NnYtMTQuMjUzek0xNi43NDIgMS4wMDR2MTQuMjU2aDE0LjI1M3YtMTQuMjU2ek0xLjAwNCAxLjAwNHYxNC4yNTZoMTQuMjU2di0xNC4yNTZ6Ij48L3BhdGg+Cjwvc3ZnPg==)](https://getkiln.ai/download) [![Linux](https://img.shields.io/badge/Linux-444444?logo=linux&logoColor=ffffff)](https://getkiln.ai/download) ![Github Downsloads](https://img.shields.io/github/downloads/kiln-ai/kiln/total)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Connect | [![Discord](https://img.shields.io/badge/Discord-Kiln_AI-blue?logo=Discord&logoColor=white)](https://getkiln.ai/discord) [![Newsletter](https://img.shields.io/badge/Newsletter-subscribe-blue?logo=mailboxdotorg&logoColor=white)](https://getkiln.ai/blog)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-[<img width="220" alt="Download button" src="https://github.com/user-attachments/assets/a5d51b8b-b30a-4a16-a902-ab6ef1d58dc0">](https://github.com/Kiln-AI/Kiln/releases/latest) [<img width="220" alt="Quick start button" src="https://github.com/user-attachments/assets/aff1b35f-72c0-4286-9b28-40a415558359">](https://docs.getkiln.ai/getting-started/quickstart)
+[<img width="220" alt="Download button" src="https://github.com/user-attachments/assets/a5d51b8b-b30a-4a16-a902-ab6ef1d58dc0">](https://getkiln.ai/download) [<img width="220" alt="Quick start button" src="https://github.com/user-attachments/assets/aff1b35f-72c0-4286-9b28-40a415558359">](https://docs.getkiln.ai/getting-started/quickstart)
 
 ## Key Features
 
@@ -46,7 +46,7 @@
 
 The Kiln desktop app is completely free. Available on MacOS, Windows and Linux.
 
-[<img width="220" alt="Download button" src="https://github.com/user-attachments/assets/a5d51b8b-b30a-4a16-a902-ab6ef1d58dc0">](https://github.com/Kiln-AI/Kiln/releases/latest)
+[<img width="220" alt="Download button" src="https://github.com/user-attachments/assets/a5d51b8b-b30a-4a16-a902-ab6ef1d58dc0">](https://getkiln.ai/download)
 
 ## Demo
 

app/desktop/WinInnoSetup.iss

@@ -3,7 +3,7 @@
 
 #define MyAppPath "build\dist\Kiln"
 #define MyAppName "Kiln"
-#define MyAppVersion "0.16.0"
+#define MyAppVersion "0.17.0"
 #define MyAppPublisher "Chesterfield Laboratories Inc"
 #define MyAppURL "https://getkiln.ai"
 #define MyAppExeName "Kiln.exe"

app/desktop/desktop_server.py

@@ -1,4 +1,6 @@
+import asyncio
 import contextlib
+import os
 import threading
 import time
 from contextlib import asynccontextmanager
@@ -7,6 +9,7 @@
 import kiln_server.server as kiln_server
 import uvicorn
 from fastapi import FastAPI
+from kiln_ai.utils.logging import setup_litellm_logging
 
 from app.desktop.log_config import log_config
 from app.desktop.studio_server.data_gen_api import connect_data_gen_api
@@ -21,6 +24,12 @@
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
+    # debug event loop, warning on hangs
+    should_debug = os.environ.get("DEBUG_EVENT_LOOP", "false") == "true"
+    if should_debug:
+        loop = asyncio.get_event_loop()
+        loop.set_debug(True)
+
     # Set datamodel strict mode on startup
     original_strict_mode = datamodel_strict_mode.strict_mode()
     datamodel_strict_mode.set_strict_mode(True)
@@ -30,6 +39,8 @@ async def lifespan(app: FastAPI):
 
 
 def make_app():
+    setup_litellm_logging()
+
     app = kiln_server.make_app(lifespan=lifespan)
     connect_provider_api(app)
     connect_prompt_api(app)

app/desktop/dev_server.py

@@ -1,13 +1,18 @@
 # Run a desktop server for development:
 # - Auto-reload is enabled
 # - Extra logging (level+colors) is enabled
+import os
+
 import uvicorn
 
 from app.desktop.desktop_server import make_app
 
 # top level app object, as that's needed by auto-reload
 dev_app = make_app()
 
+os.environ["DEBUG_EVENT_LOOP"] = "true"
+
+
 if __name__ == "__main__":
     uvicorn.run(
         "app.desktop.dev_server:dev_app",

app/desktop/log_config.py

@@ -2,7 +2,7 @@
 from enum import Enum
 from typing import List
 
-from kiln_ai.utils.config import Config
+from kiln_ai.utils.logging import get_default_formatter, get_log_file_path
 
 
 class LogDestination(Enum):
@@ -15,20 +15,6 @@ def get_log_level() -> str:
     return os.getenv("KILN_LOG_LEVEL", "WARNING")
 
 
-def get_log_file_path() -> str:
-    """Get the path to the log file, using environment override if specified.
-
-    Returns:
-        str: The path to the log file
-    """
-    log_path_default = os.path.join(Config.settings_dir(), "logs", "kiln_desktop.log")
-    log_path = os.getenv("KILN_LOG_FILE", log_path_default)
-
-    # Ensure the log directory exists
-    os.makedirs(os.path.dirname(log_path), exist_ok=True)
-    return log_path
-
-
 def get_max_file_bytes() -> int:
     """
     The maximum number of bytes to write to the log file.
@@ -47,10 +33,6 @@ def get_max_backup_count() -> int:
     return int(os.getenv("KILN_LOG_BACKUP_COUNT", default_backup_count))
 
 
-def get_default_formatter() -> str:
-    return "%(asctime)s.%(msecs)03d - %(levelname)s - %(name)s - %(message)s"
-
-
 def get_handlers() -> List[str]:
     destination = os.getenv("KILN_LOG_DESTINATION", "all")
     handlers = {
@@ -86,7 +68,7 @@ def log_config():
                 "class": "logging.handlers.RotatingFileHandler",
                 "level": get_log_level(),
                 "formatter": "logformatter",
-                "filename": get_log_file_path(),
+                "filename": get_log_file_path("kiln_desktop.log"),
                 "mode": "a",
                 "maxBytes": get_max_file_bytes(),
                 "backupCount": get_max_backup_count(),

app/desktop/studio_server/data_gen_api.py

@@ -7,8 +7,13 @@
     DataGenSampleTaskInput,
     wrap_task_with_guidance,
 )
+from kiln_ai.adapters.ml_model_list import (
+    default_structured_output_mode_for_model_provider,
+)
 from kiln_ai.adapters.model_adapters.base_adapter import AdapterConfig
 from kiln_ai.datamodel import DataSource, DataSourceType, PromptId, TaskRun
+from kiln_ai.datamodel.prompt_id import PromptGenerators
+from kiln_ai.datamodel.task import RunConfigProperties
 from kiln_server.run_api import model_provider_from_string
 from kiln_server.task_api import task_from_id
 from pydantic import BaseModel, ConfigDict, Field
@@ -92,8 +97,15 @@ async def generate_categories(
 
         adapter = adapter_for_task(
             categories_task,
-            model_name=input.model_name,
-            provider=model_provider_from_string(input.provider),
+            run_config_properties=RunConfigProperties(
+                model_name=input.model_name,
+                model_provider_name=model_provider_from_string(input.provider),
+                prompt_id=PromptGenerators.SIMPLE,
+                # We don't expose setting this manually in the UI, so pull a recommended mode from ml_model_list
+                structured_output_mode=default_structured_output_mode_for_model_provider(
+                    input.model_name, model_provider_from_string(input.provider)
+                ),
+            ),
         )
 
         categories_run = await adapter.invoke(task_input.model_dump())
@@ -115,8 +127,15 @@ async def generate_samples(
 
         adapter = adapter_for_task(
             sample_task,
-            model_name=input.model_name,
-            provider=model_provider_from_string(input.provider),
+            run_config_properties=RunConfigProperties(
+                model_name=input.model_name,
+                model_provider_name=model_provider_from_string(input.provider),
+                prompt_id=PromptGenerators.SIMPLE,
+                # We don't expose setting this manually in the UI, so pull a recommended mode from ml_model_list
+                structured_output_mode=default_structured_output_mode_for_model_provider(
+                    input.model_name, model_provider_from_string(input.provider)
+                ),
+            ),
         )
 
         samples_run = await adapter.invoke(task_input.model_dump())
@@ -139,9 +158,16 @@ async def save_sample(
 
         adapter = adapter_for_task(
             task,
-            model_name=sample.output_model_name,
-            provider=model_provider_from_string(sample.output_provider),
-            prompt_id=sample.prompt_method,
+            run_config_properties=RunConfigProperties(
+                model_name=sample.output_model_name,
+                model_provider_name=model_provider_from_string(sample.output_provider),
+                prompt_id=sample.prompt_method,
+                # We don't expose setting this manually in the UI, so pull a recommended mode from ml_model_list
+                structured_output_mode=default_structured_output_mode_for_model_provider(
+                    sample.output_model_name,
+                    model_provider_from_string(sample.output_provider),
+                ),
+            ),
         )
 
         properties: dict[str, str | int | float] = {