[OPIK-5184] [SDK] feat: Make Prompt and ChatPrompt resilient to backend sync failures

[petrotiurin]

Details

Prompt() and ChatPrompt() constructors (Python) and createPrompt()/createChatPrompt() (TypeScript) now gracefully handle backend unavailability instead of crashing. When the backend is unreachable, prompts work locally and can be synced later via sync_with_backend() / syncWithBackend().

Key changes across both SDKs:

• Backend sync errors (API errors, connection errors, timeouts) are caught and logged as warnings instead of propagating
• Non-API errors (e.g. ValueError, TypeError, PromptTemplateStructureMismatch) still propagate normally
• Added synced property to check if a prompt was successfully persisted
• Added public sync_with_backend() / syncWithBackend() method for manual retry
• Unsynced prompts still support format() and all local operations

Change checklist

• User facing
• Documentation update

Issues

• OPIK-5184

AI-WATERMARK

AI-WATERMARK: yes

• Tools: Claude Code
• Model(s): Claude Opus 4.6
• Scope: full implementation
• Human verification: code review + unit tests

Testing

Python SDK:

cd sdks/python
python -m pytest tests/unit/api_objects/prompt/test_prompt_sync.py -v  # 14 tests
python -m pytest tests/unit/api_objects/test_opik_client.py::TestOpikClientCreateChatPrompt -v  # 2 tests

All 16 tests pass. Pre-commit hooks (ruff, ruff-format, mypy) pass.

TypeScript SDK:

cd sdks/typescript
npx vitest run tests/unit/client/client-prompts.test.ts  # 31 tests
npx vitest run tests/unit/client/client-chat-prompts.test.ts  # 11 tests

All 42 tests pass. tsc --noEmit passes with zero errors.

Scenarios validated:

• Prompt created despite API 500, API 503, connection error, timeout (parametrized)
• sync_with_backend() returns False/false on failure, True/true on success
• synced property reflects current sync state
• Non-API errors (ValueError, TypeError) propagate and prevent construction
• Existing tests for ChatPrompt creation updated for renamed method

Documentation

N/A

🤖 Generated with Claude Code