P0-REL-C: Code Quality & Public API — Ruff Clean, __all__, Internal Code Cleanup

[DingmaomaoBJTU]

Summary

Define and freeze the stable public API surface, clean up internal code, ensure ruff lint is clean, and all tests pass in a clean environment.

Context

Code quality tasks must complete by May 19. The public API surface definition is critical — once the package is released, breaking changes require a major version bump. From plans/release/0501_release_plan/release.md.

Tasks (C-01 ~ C-06)

• C-01: Define and document the stable public API surface — annotate __all__ in all modules; mark internal APIs with _ prefix
• C-02: Remove or gate all internal-only code paths and debug flags — grep for TODO: internal, INTERNAL, MS-only markers
• C-03: Ruff lint clean pass across entire codebase — uv run ruff check . --fix; zero lint errors before release
• C-04: Review and clean up configuration schema (wmk config) — final schema must be stable at release; document breaking-change policy
• C-05: Ensure all pytest tests pass on a clean environment — run on a fresh uv venv with only released dependencies
• C-06: Check for leftover debug output / print() statements in production code — replace with structured logging (coordinate with P1-INFRA-004)

Acceptance Criteria

• All public modules have __all__ defined; internal APIs prefixed with _
• Zero internal-only markers (INTERNAL, MS-only) remaining in code
• uv run ruff check . exits with code 0 (zero lint errors)
• Configuration schema documented and frozen for v0.1.0
• uv run pytest tests/ passes on a fresh venv (clean environment, no leftover state)
• Zero bare print() calls in non-test production code

Technical Notes

• CARDINAL RULE Adding Microsoft SECURITY.MD #2: always run uv run ruff check . --fix after any Python changes
• __all__ should export only the intended public API — not all imported symbols
• C-05 clean environment: uv venv --python 3.11 && uv sync && uv run pytest tests/
• C-06 can be done incrementally — track via grep: grep -rn "^print(" modelkit/

Related Files

• plans/release/0501_release_plan/release.md — C-01 ~ C-06 task details
• P1-INFRA-004 — Logging & Telemetry (upstream for C-06)