fix(sdk): return annotation create response

[bhushanasati25]

Summary

• return the underlying HTTPClient.post() result from BaseAnnotation.create() / UserFeedback.create()
• document that callers receive the API response on success and None when the HTTP client cannot complete the write
• add regression coverage for both success and failure return values

Fixes #4402.
Also addresses duplicate #4404.

Tests

• env PYTHONPATH=../opentelemetry-semantic-conventions-ai .venv-codex/bin/python -m pytest tests/test_user_feedback.py -q
• .venv-codex/bin/ruff check traceloop/sdk/annotation/base_annotation.py traceloop/sdk/annotation/user_feedback.py tests/test_user_feedback.py
• git diff --check

Checklist

• I have added tests that cover my changes.
• If adding a new instrumentation or changing an existing one, I've added screenshots from some observability platform showing the change.
• PR name follows conventional commits format: feat(instrumentation): ... or fix(instrumentation): ....
• (If applicable) I have updated the documentation accordingly.

Summary by CodeRabbit

• New Features

  • Feedback submissions now return a success response when completed.
  • Feedback submission results indicate when a write cannot be completed.

• Bug Fixes

  • Improved handling and reporting of unsuccessful feedback submissions.

• Tests

  • Added coverage for successful feedback responses and failed write operations.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 9d3adeb0-9329-4760-b798-2b2ce1fb7a04

📥 Commits

Reviewing files that changed from the base of the PR and between 62e24c2 and c59714e.

📒 Files selected for processing (3)

• packages/traceloop-sdk/tests/test_user_feedback.py
• packages/traceloop-sdk/traceloop/sdk/annotation/base_annotation.py
• packages/traceloop-sdk/traceloop/sdk/annotation/user_feedback.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Annotation creation now returns the HTTP write result. User feedback tests verify successful responses and a None result when the HTTP write fails.

Changes

Annotation feedback

Layer / File(s)	Summary
Return the annotation write result packages/traceloop-sdk/traceloop/sdk/annotation/base_annotation.py, packages/traceloop-sdk/traceloop/sdk/annotation/user_feedback.py	create now returns the HTTP response and documents the API response or None result.
Validate return values packages/traceloop-sdk/tests/test_user_feedback.py	Tests assert successful feedback creation returns {"status": "success"} and failed writes return None.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to c5971

This localized change returns annotation API responses to callers and documents success and failure behavior; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: annotation creation now returns the underlying response.
Linked Issues check	✅ Passed	The change addresses issue #4402 by returning the existing HTTPClient.post() result from annotation creation methods. Callers can now distinguish successful writes from None failures, while non-raisin…
Out of Scope Changes check	✅ Passed	All changes are limited to annotation return values, related documentation, and regression tests. No unrelated code changes are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files.

Full details: Linked Issues check

Explanation

The change addresses issue #4402 by returning the existing HTTPClient.post() result from annotation creation methods. Callers can now distinguish successful writes from None failures, while non-raising behavior remains unchanged. Regression tests cover both outcomes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}