Kiln-AI
diff --git a/‎.agents/api_code_review.md‎
Lines changed: 59 additions & 0 deletions b/‎.agents/api_code_review.md‎
Lines changed: 59 additions & 0 deletions
diff --git a/‎.agents/code_review_guidelines.md‎
Lines changed: 13 additions & 1 deletion b/‎.agents/code_review_guidelines.md‎
Lines changed: 13 additions & 1 deletion
diff --git a/‎.coderabbit.yaml‎
Lines changed: 3 additions & 0 deletions b/‎.coderabbit.yaml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.config/wt.toml‎
Lines changed: 3 additions & 0 deletions b/‎.config/wt.toml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.config/wt/start.sh‎
Lines changed: 18 additions & 1 deletion b/‎.config/wt/start.sh‎
Lines changed: 18 additions & 1 deletion
diff --git a/‎.cursor/skills/specs/SKILL.md‎
Lines changed: 0 additions & 134 deletions b/‎.cursor/skills/specs/SKILL.md‎
Lines changed: 0 additions & 134 deletions
diff --git a/‎.cursor/skills/specs/references/cmd_code_review.md‎
Lines changed: 0 additions & 69 deletions b/‎.cursor/skills/specs/references/cmd_code_review.md‎
Lines changed: 0 additions & 69 deletions
@@ -0,0 +1,59 @@
+# FastAPI / OpenAPI Standards
+
+Our OpenAPI spec drives our SDK, Scalar docs, and agent tool use (Kiln Chat calls our APIs). Every endpoint must be well-documented and consistently named. Flag violations during code review.
+
+**Required on every endpoint:**
+
+1. **`tags=[...]`** on the route decorator. Every endpoint must belong to a tag group (e.g. `tags=["Projects"]`). Untagged endpoints break Scalar navigation and agent tool discovery. Prefer existing tags, creating new ones only when really needed. All tags should be documented in `tags_metadata` in `server.py`
+2. **`summary=`** on the route decorator. A short, unique name for the operation. Summaries must be unambiguous — if two endpoints could share the same summary (e.g. "Edit Tags"), qualify them ("Edit Run Tags", "Edit Document Tags").
+3. **Docstring** on the handler function (optional if behavior is completely obvious from the path, method, and summary). When provided, docstrings should be terse — one sentence or a fragment. Never pad with filler like "This endpoint allows you to...". Longer descriptions (2–3 sentences) are warranted only when distinguishing easily confused endpoints, documenting non-obvious side effects, or noting prerequisites. Exclude if the `summary` string already covers the same level of detail.
+4. **`Path(description=...)`** on every path parameter, using `Annotated[str, Path(description="...")]` syntax. Recurring ID parameters must use consistent standard descriptions (e.g. `"The unique identifier of the project."`, `"The unique identifier of the task within the project."`).
+5. **`Query(description=...)`** on every query parameter.
+6. **`Field(description=...)`** on Pydantic model properties that aren't completely self-evident from name + type.
+7. **Class docstring** on Pydantic models used as API request/response bodies. These become the schema description in the OpenAPI spec, which agents and SDK users see when inspecting request/response types. Optional but suggested if non-obvious from name.
+
+**Correct HTTP methods:**
+
+- **GET** must be idempotent and side-effect-free. If an endpoint creates, modifies, or deletes data, it must not be GET. We previously had GET endpoints that established connections and ran evaluations — this is wrong and confuses both agents and humans.
+- **POST** for creation and actions that trigger execution.
+- **PATCH** for partial updates.
+- **DELETE** for deletion.
+- The only exception is SSE streaming endpoints, which must use GET due to browser `EventSource` constraints. These must have descriptions explicitly noting the mutation and the SSE reason.
+
+**Naming and path conventions:**
+
+- **Always use plural nouns** in path segments: `/tasks/{task_id}`, never `/task/{task_id}`. Same for `/projects`, `/specs`, `/evals`, `/runs`, `/prompts`, `/documents`, `/skills`, `/run_configs`, etc. We had inconsistencies where GET used plural but POST/PATCH/DELETE used singular — this is confusing and must be caught.
+- **Paths should be descriptive and intuitive.** Paths should follow REST conventions and be clear (as possible) without docstrings. Path and descriptions should distinguishing similar sounding endpoints. If a path could reasonably be improved, suggest a rename.
+- **Consistent path structure** for related resources. All operations on the same resource type should share a common path prefix (e.g. all run config operations under `/run_configs`, not split across `/task_run_config`, `/mcp_run_config`, `/run_config`). Important to not use similar but different prefixes, as this commonly trips up agents.
+- **No trailing slashes** on paths. Use `/run_configs` not `/run_configs/`. Trailing slashes cause inconsistency between endpoints and can break client routing.
+
+**Example of a well-documented endpoint:**
+
+```python
+@app.delete(
+    "/api/projects/{project_id}",
+    summary="Delete Project",
+    tags=["Projects"],
+)
+async def delete_project(
+    project_id: Annotated[
+        str, Path(description="The unique identifier of the project.")
+    ],
+) -> dict:
+    """Removes the project from Kiln but does not delete the files from disk."""
+```
+
+**What to flag in code review:**
+
+- Missing `tags=` on any route decorator
+- Missing `summary=` on any route decorator
+- Missing `Path(description=...)` or `Query(description=...)` on any parameter
+- GET endpoints that perform mutations (unless SSE with documented justification)
+- Singular nouns in path segments where plural is standard
+- Ambiguous or duplicate summaries across endpoints
+- Trailing slashes on paths
+- Inconsistent path naming for the same resource type
+- Wordy or filler-padded docstrings ("This endpoint allows you to...")
+- Docstrings containing code artifacts, raw `Args:` blocks, or formatting that doesn't read as clean prose in OpenAPI
+- Pydantic models used in API request/response types (nested included) missing a class docstring, if the class name alone isn't obvious
+- Custom string types with validator-based constraints that don't surface in the OpenAPI schema. Use `StringConstraints` in the `Annotated` type definition so `minLength`/`maxLength` appear automatically (see `FilenameString`, `SkillNameString` for examples). Don't duplicate constraints in individual `Field()` calls.
@@ -13,7 +13,6 @@
 - Editing globals: rarely a good idea. When done it should be thoughtful and clear: singletons clearly designed to be singletons and labeled as such. Never set globals on external libs (structlog) unless this project is an “application” (server always run at top level) and not a library (potentially called from many apps).
 
 ### Python specific guide
-
 - Code should be "Pythonic"
 - We use `asyncio` where ever possible. Avoid threads unless there's a good reason we can't use async.
 - Python json.dumps should always set `ensure_ascii=False`
@@ -25,3 +24,16 @@ The SDK in `/libs/core` is a SDK/library we expose to third parties. We code rev
 - Changing existing APIs that break current users should be avoided. Call out breaking API changes, and confirm with user that we're okay with this break.
 - All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd party docs automatically. The doc strings should be written for 3rd party devs learning the SDK.
 - Performance: the base_adapter and litellm_adapter are performance critical. They are the core run-loop of our agent system. We should avoid anything that would slow them down (file reads should be done once and passed in, etc). It's critical to avoid blocking IO - a process may be executing hundreds of these in parallel.
+
+### FastAPI / OpenAPI Standards
+
+If the change impacts API endpoints, read `.agents/api_code_review.md` for instructions on how to code review API endpoints.
+
+Changes impacting APIs include:
+ - adding/removing/modifying a FastAPI endpoint `@app.get`, `@app.delete`, etc
+ - adding/removing/modifing a pydantic model which is used in an API endpoint, as a input/return value (including nested models)
+
+### Project specific guide
+
+- **`ModelName` enum and user input:** Do not use the `ModelName` enum for validation or typing of user-provided model identifiers (for example in a Pydantic request body that validates an API payload). Kiln loads additional models over the air; those models can use names that are not members of the locally shipped `ModelName` enum. If request validation is tied to the enum, a model that is valid according to the merged model list will fail validation. Appropriate uses of `ModelName` include aliasing a constant chosen at build time (for example default config that references a known shipped model) and entries inside the `ml_model_list` provider definitions.
+
@@ -0,0 +1,3 @@
+reviews:
+  path_filters:
+    - "!app/desktop/studio_server/api_client/kiln_ai_server_client/**"
@@ -2,5 +2,8 @@
 deps = "uv sync && cd app/web_ui && npm install"
 claude = "utils/setup_claude.sh"
 
+[post-start]
+copy = "wt step copy-ignored"
+
 [pre-remove]
 session = "zellij delete-session {{ branch | sanitize }} 2>/dev/null || true"
@@ -16,11 +16,28 @@ SESSION_NAME="${BRANCH//\//-}"
 hash_port() {
     printf '%s' "$1" | cksum | awk '{print ($1 % 10000) + 10000}'
 }
-PORT=$(hash_port "$BRANCH")
+
+port_free() {
+    ! lsof -iTCP:"$1" -sTCP:LISTEN -t >/dev/null 2>&1
+}
+
+BASE_PORT=$(hash_port "$BRANCH")
+PORT=$BASE_PORT
+while ! port_free "$PORT" || ! port_free "$((PORT + 1))"; do
+    PORT=$((PORT + 1))
+    if [ "$PORT" -ge 20000 ]; then
+        PORT=10000
+    fi
+    if [ "$PORT" -eq "$BASE_PORT" ]; then
+        echo "ERROR: no free port pair found in range 10000-19999" >&2
+        exit 1
+    fi
+done
 
 export KILN_PORT="$PORT"
 export KILN_FRONTEND_PORT="$((PORT + 1))"
 export VITE_API_PORT="$PORT"
+export VITE_BRANCH_NAME="$BRANCH"
 
 export KILN_WEB_URL="http://localhost:$KILN_FRONTEND_PORT"
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+reviews:`
	`2`	`+ path_filters:`
	`3`	`+ - "!app/desktop/studio_server/api_client/kiln_ai_server_client/**"`