code-style

---
name: code-style
description: >
  Apply railtracks' code-style conventions whenever writing or editing Python code in this repo:
  new functions, modified signatures, docstrings, comments, imports, error handling. Use this
  automatically as part of any code change, not just when explicitly asked to clean up code.
---

# railtracks Code Style

Code changes in this repo should be reviewed against these rules. Each one comes from a
recurring, repeated PR review comment on railtracks, not a hypothetical style preference.

- **Lint/format**: run `ruff check --fix` and `ruff format`, required for every PR (CI-enforced).
- **Imports**: prefer top-level imports. Local/inline imports are fine when there's a real reason (e.g.
  deferring an expensive or optional dependency like `litellm`); don't add them out of habit, and don't
  let a lint failure be the excuse either way.
- **Tests**: new functionality gets tests in the matching package's `tests/` directory; don't leave a
  behavior change uncovered.
- **Docstrings**: must match the actual signature (param names, types, `| None` / `Iterable[...]` etc.).
  Update the docstring any time a signature changes.
- **Tool docstrings/type hints**: for any `@rt.function_node`-wrapped tool, the docstring is the literal
  tool description the LLM sees and the type hints define its JSON schema parameters; don't write vague
  docstrings or omit type hints on a tool function.
- **Module-level comment strings**: a docstring at the top of a file is welcome. Avoid long inline
  paragraph-style comments in the body of the code; keep inline comments short and targeted.
- **Typing**: no bare `Any` when a concrete type is available or already imported nearby. Don't reach for
  `Any` as a quick fix to silence something that's actually broken, either; fix the real type mismatch.
- **TODOs**: no inline `# TODO` comments. Either fix it now or file a tracked GitHub issue and reference it.
- **Cruft**: no dead/commented-out code, no stray debug/scratch files left in a change.
- **Documentation paragraphs**: keep prose paragraphs on one line, matching the existing docs; do not hard-wrap sentences. Preserve code-block formatting.
- **Mutable defaults**: don't store a mutable default (`x or []`) by reference and mutate it later; copy
  defensively.
- **Errors**: use `repr(e)` rather than `str(e)` in error/log messages.
- **`__init__.py`**: don't add docstrings to `__init__.py` files; not this repo's convention.
- **Consistency with siblings**: when adding a new variant of something that already has 2+ siblings
  (chunkers, loaders, LLM providers, etc.), match their existing shape/behavior rather than introducing an
  ad hoc one-off.
- **Model references in examples**: use current, provider-documented model IDs in user-facing examples and
  bundled CLI skills. Verify IDs against the provider's model catalog and deprecation page when adding or
  refreshing examples. Keep a model-specific reference only when the example demonstrates behavior unique
  to that model, and explain that choice nearby when it would otherwise look stale. Historical upgrade
  guides and tests that intentionally exercise model-name passthrough may retain older IDs.