feat: persist task description in tip entity metadata

[jayaramkr]

generate_tips() now returns a TipGenerationResult containing both the tips and the source task_description. Both callers (PhoenixSync and MCP save_trajectory) store task_description in tip entity metadata, enabling future clustering of tips by task similarity.

Trajectories without a task description default to "Task description unknown".

Summary by CodeRabbit

• Refactor
  • Tip generation now returns both tips and an associated task description, and that description is included with generated tips.
• Bug Fixes
  • Sync/storage only creates or updates guideline entries when generated tips are present and persists the task description with each tip.
• Tests
  • Unit tests updated and added to validate the new tip result shape and task description handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

generate_tips now returns TipGenerationResult (tips + task_description); consumers (mcp_server, phoenix_sync) and tests updated to use result.tips and persist result.task_description in guideline/tip metadata. Only update guidelines when result.tips is non-empty.

Changes

Cohort / File(s)	Summary
Schema kaizen/schema/tips.py	Added TipGenerationResult dataclass with fields tips: list[Tip] and task_description: str.
Tip generation kaizen/llm/tips/tips.py	Changed generate_tips to return TipGenerationResult; extract task_description from trajectory (fallback "Task description unknown"); always return result object even on errors/empty tips.
Frontend / MCP server kaizen/frontend/mcp/mcp_server.py	Consume generate_tips as result; only update guideline entities when result.tips is non-empty; include task_description in guideline metadata; keep conflict-resolution behavior unchanged per path.
Sync layer kaizen/sync/phoenix_sync.py	Use result = generate_tips(...); branch and iterate over result.tips; persist result.task_description in tip metadata; return counts based on result.tips.
Tests tests/unit/test_phoenix_sync.py, tests/unit/test_tips.py	Mocks updated to return TipGenerationResult(...); tests assert task_description extraction/persistence and added trajectory parsing tests for task_description fallback.

Sequence Diagram(s)

(Skipped — changes are plumbing/metadata threading between generator and consumers; no new complex multi-component sequential flow.)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Persist task description in tip entity metadata #61: Implements TipGenerationResult and threads task_description through generate_tips → schema → phoenix_sync/mcp_server, matching the PR's objectives.

Possibly related PRs

• Add Phoenix trajectory extraction and sync functionality #18: Directly modifies tip-generation return type and phoenix_sync usage; strong code-level overlap.
• Tips Improvement #20: Touches tip generation and schema usage that overlap with the new TipGenerationResult type.
• Improve trajectory storage and fix schema handling #30: Modifies phoenix_sync and trajectory handling; affects similar sync/tip-generation integration points.

Suggested reviewers

• vinodmut
• visahak

Poem

🐰 I gathered tips and a task to share,
A small description tucked in with care.
From generator to sync the metadata flows,
Little guidelines bloom where the rabbit goes. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: persisting task description in tip entity metadata across multiple modules and syncing processes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (2)

kaizen/frontend/mcp/mcp_server.py (1)

101-119: Missing guard for empty tips list.

Unlike phoenix_sync.py (line 474), which checks if result.tips: before calling update_entities, this code unconditionally calls update_entities even when result.tips is empty, passing an empty entity list. This is a pre-existing inconsistency, but worth aligning now to avoid a needless round-trip (or potential error if the backend doesn't expect an empty list).

Proposed fix

     result = generate_tips(messages)
 
-    get_client().update_entities(
-        namespace_id=kaizen_config.namespace_id,
-        entities=[
-            Entity(
-                type="guideline",
-                content=tip.content,
-                metadata={
-                    "category": tip.category,
-                    "rationale": tip.rationale,
-                    "trigger": tip.trigger,
-                    "task_description": result.task_description,
-                },
-            )
-            for tip in result.tips
-        ],
-        enable_conflict_resolution=True,
-    )
+    if result.tips:
+        get_client().update_entities(
+            namespace_id=kaizen_config.namespace_id,
+            entities=[
+                Entity(
+                    type="guideline",
+                    content=tip.content,
+                    metadata={
+                        "category": tip.category,
+                        "rationale": tip.rationale,
+                        "trigger": tip.trigger,
+                        "task_description": result.task_description,
+                    },
+                )
+                for tip in result.tips
+            ],
+            enable_conflict_resolution=True,
+        )

tests/unit/test_phoenix_sync.py (1)

537-579: Consider asserting task_description in entity metadata.

The mock correctly uses TipGenerationResult, but no test verifies that task_description actually appears in the guideline entity metadata passed to update_entities. Since persisting task_description is the core goal of this PR, a targeted assertion would prevent regressions.

For example, in test_sync_processes_valid_spans:

# After result assertions, verify metadata includes task_description
tip_update_call = phoenix_sync.client.update_entities.call_args_list[-1]
tip_entities = tip_update_call[1]["entities"]  # or tip_update_call.kwargs["entities"]
assert all("task_description" in e.metadata for e in tip_entities)

[jayaramkr]

Addresses #61

[vinodmut]

We're using tips and guidelines somewhat interchangeably. Let's pick one. See #62

No need to block this PR on this, but let's decide soon.