Kiln AI Documentation

Git Auto Sync is a feature designed to provide a seamless, non-technical user experience for version control. It abstracts Git operations (pull, sync, merge, and commit) behind a FastAPI middleware, allowing users to work with the Kiln data model without manually managing Git commands, merge conflicts, or push/pull cycles.

Key features include:

• Auto Mode: Automatically manages git pull/sync/merge in the background.
• Manual Mode: The existing behavior where users manage Git themselves.
• Atomic Commits: Ensures that all file changes made during a single API call are committed as a single batch to prevent partial or invalid states.

Kiln is a workbench for the full AI development loop. Key features include:

• Evals: Auto-generate evaluation datasets (judge + synthetic) to align models to preferences.
• Auto-Optimize: Automatically find the best prompt, model selection, tools, skills, and parameters.
• RAG: Drag-and-drop documents (PDF, image, video, audio) to create RAG systems with auto-generated evals.
• Agents: Compose multi-agent hierarchies where each agent runs in its own focused context window.
• Synthetic Data: Generate data for evals or fine-tuning.
• Fine-Tuning: Zero-code fine-tuning across 60+ models (e.g., Qwen, Llama, GPT, Gemini) on providers like Fireworks, Together, and Vertex.
• Local-first: Runs on your machine. Supports bringing your own API keys or running fully offline with Ollama.

Kiln uses a recursive adapter-based architecture for agents and sub-agents.

Adapter Lifecycle

Adapters are short-lived. They are created per request via adapter_for_task(), invoked exactly once via BaseAdapter.invoke(), and then discarded.

Sub-Agent Chains

Agents can trigger sub-agents through the KilnTaskTool. This creates a recursive chain:

1. Root Agent (e.g., LiteLlmAdapter) runs and processes tool calls.
2. If a KilnTaskTool.run() is called, it triggers adapter_for_task().
3. This creates a NEW adapter for the sub-task.
4. The sub-agent's execution can then trigger its own MCPServerTool.run() calls.

Parallel Tool Execution

Tools within a single agent turn are executed concurrently using asyncio.gather. This allows multiple MCP tool calls to run simultaneously within a single model turn.

The Kiln Agent API endpoints are designed with three primary goals to optimize LLM performance and efficiency:

1. Token-efficiency: Responses return only the "key info" required for decision-making. Long free-form text is truncated to save context window space.
2. Comprehensive coverage: The agent_overview endpoint ensures every top-level entity type in a project or task is mentioned, preventing the agent from overlooking available capabilities.
3. Reduced latency (No many-call loops): Instead of requiring the agent to make multiple sequential calls (e.g., for evaluation results), the API provides single, server-side aggregated payloads.

Agents access these endpoints via the existing call_kiln_api tool; no new tool registration is required.

Kiln uses ISO 8601 strings for storing datetimes (e.g., TaskRun.created_at). To support cross-timezone collaboration, new writes include the writer's local timezone offset.

Storage Formats:

• New Writes (Aware): ISO 8601 with offset, e.g., 2026-04-16T09:26:04.806292-04:00 or 2026-04-16T21:26:26.944258+08:00.
• Legacy Data (Naive): Naive ISO strings without offset, e.g., 2026-04-16T09:26:04.806292.

Read/Rendering Logic:

• Aware datetimes: Parsed using the provided offset.
• Naive datetimes: Interpreted as the writer's local time (not UTC). This ensures single-user setups remain correct as the writer and reader share the same local time.
• UI Rendering: The web frontend uses the formatDate helper (located in app/web_ui/src/lib/utils/formatters.ts), which utilizes new Date(dateString). This renders timestamps in the viewer's local time.

Git Auto Sync provides automatic, transparent synchronization for Kiln projects, enabling cloud sync, version history, and multi-user collaboration. It is designed for non-technical users to manage synchronization entirely through the Kiln UI without needing git knowledge.

Key Features:

• Automatic Sync: Handles pull, commit, push, conflict resolution, and crash recovery automatically.
• Conflict Avoidance: Uses small, frequent commits and an append-only data model to minimize conflicts. The system maintains a background poller to keep the local repository within 15 seconds of the remote.
• Online-only Mode: To prevent divergence, the system requires an active connection. Going offline will result in 503 errors for reads and writes rather than allowing silent divergence.
• Data Safety: Changes are always committed or stashed in conflict cases; no data is deleted.

Kiln projects are organized as directories containing .kiln JSON files. This structure ensures Git compatibility and allows for easy data manipulation using tools like pandas or polars.

Hierarchy:

• Project: Organizes related tasks.
• Task: Contains prompt instructions, input/output schemas, and requirements.
• TaskRun: A specific execution instance including input, output, and human ratings.
• Finetune: Configuration and status for model fine-tuning.
• Prompt: A specific prompt associated with a task.
• DatasetSplit: A collection of task runs divided into train/test/validation sets.

Git Auto Sync provides transparent git-based synchronization for Kiln projects by operating at the HTTP middleware level. It does not require changes to libs/core/ or KilnBaseModel. The system observes file I/O and uses git status to commit changes after they occur.

The architecture consists of four primary components:

1. FastAPI Middleware: Manages write locks for mutating requests and handles commits/pushes upon request completion.
2. GitSyncManager: The core engine responsible for locking, using pygit2 for operations, and managing commit/push/rollback cycles.
3. Background Sync: An asynchronous poller that ensures local repositories remain fresh.
4. Manager Registry: A singleton that manages individual GitSyncManager instances for each repository.

The Chat Pane operates in two distinct modes depending on the route and screen size:

1. Full-screen Mode: Accessible via the /chat route. In this mode, the sidebar and the floating chat icon are hidden to avoid redundancy.
2. Sidebar Mode: A panel on the right side of the app layout used for side-by-side interaction. This is available on all other routes.

Toggle Behavior:

• Use the X button within the sidebar to collapse it.
• When collapsed, a floating chat icon appears in the bottom-right corner of the layout. Clicking this icon re-expands the sidebar.

Kiln is organized as a monorepo containing several distinct sub-projects. Depending on your goal (using the core logic, deploying a server, or running the desktop application), you will interact with different directories:

• Core Functionality: Located in libs/core/. This is the Python library containing evals, synthetic data generation, fine-tuning, RAG, and other core AI capabilities.
• REST API: Located in libs/server/. A FastAPI server that wraps the core library.
• Web Frontend: Located in app/web_ui/. A Svelte-based web application.
• Desktop Application: Located in app/desktop/. A PyInstaller-packaged Python application that runs a FastAPI server, hosts the web app, and launches a browser for the UI.