Rename model-client chat() → response(), add solve_physics_problem() and Batch API support

[sherryzyh]

Summary

This branch reworks the model-client layer in two substantive ways and ships a formatting cleanup:

1. Rename the low-level call chat() → response() and add a high-level solve_physics_problem() entry point, aligning the client surface with OpenAI's responses.create.
2. Add synchronous Batch API support across OpenAI, Anthropic, and Gemini (~50% of sync cost), with provider-agnostic status/result types.

6 commits · 44 files · +2,075 / −374. Branch is a clean fast-forward over main (no divergence).

⚠️ Breaking change: the public client method chat() is renamed to response(). A deprecated chat() alias is kept that warns and forwards, so existing callers keep working but should migrate.

What changed

1. API rename + high-level entry point (111d25c, dff9d01)

• chat() → response(); prompt param user_prompt → input; new keyword-only instructions (system prompt).
• When instructions is omitted, every provider except OpenAI falls back to a short DEFAULT_INSTRUCTIONS system prompt (via _resolve_instructions; OpenAI overrides to stay input-only). An explicit empty string suppresses it.
• System prompt is injected at each provider's native site: Anthropic top-level system, OpenAI instructions, openai-compatible/Ollama system message, Gemini system_instruction.
• New BaseModelClient.solve_physics_problem() dispatches on input type: str question, PhysicsProblem (formatted prompt + image_path images), or PhysicsQuestionSemantics (NotImplementedError TODO, lazily imported to keep core off semantics at import time). Output gated by the new PhysicsOutputMode enum (only ANSWER_TEXT implemented).
• New core-only modes.py and prompts.py; annotation worker's physics-expert prompt is centralized via instructions.
• Cookbooks, docs/CORE.md, README, and RELEASE_NOTES updated to the new call.

2. Batch API support (2563141, 9e719e1, b7e7052)

• BaseModelClient gains a synchronous batch lifecycle: submit_batch → poll_batch → retrieve_batch_results, plus a free-text build_batch_request(...) mirroring response() (complements the existing structured build_batch_structured_request).
• New prkit.core.model_clients.batch_types: BatchState, BatchStatus, BatchItemStatus, BatchResult normalize each provider's status enum and per-request results.
• Each provider's request-body construction is now shared between response() and the batch builders (_build_responses_body / _build_messages_params) to prevent drift. OpenAI o-family models drop temperature at build time. Unsupported providers raise NotImplementedError.
• Gemini correlation fix: batches are submitted as an uploaded keyed JSONL file (File API, src=<file>) rather than inline requests. Inline Gemini responses carry no per-request key and cannot be correlated; the keyed-JSONL path returns {"key": ..., "response": {...}} that maps reliably to each request. Dead inline submit/retrieve paths removed.
• Gated live smoke test (skipped unless GEMINI_API_KEY/GOOGLE_API_KEY set) submitting a real batch with distinct ids + unique answers, asserting each answer lands under the correct custom_id — the identity check offline mocks can't make.

3. Formatting (b6504a5)

• black applied to anthropic.py, openai.py, and tests/uq/conftest.py (pre-existing non-formatted files; CI runs black --check).

New files

• src/prkit/core/model_clients/batch_types.py, modes.py, prompts.py
• tests/prkit/core/model_clients/test_batch.py, test_batch_live.py, test_prompts.py

Testing

• black --check src tests → clean (242 files).
• pytest tests/ -x -q → 1378 passed, 1 skipped, 84% coverage.
• Live Gemini batch correlation validated by the gated smoke test (requires API key).

🤖 Generated with Claude Code