crewplus 0.2.89__py3-none-any.whl

crewplus/__init__.py

@@ -0,0 +1,10 @@
+from .services.gemini_chat_model import GeminiChatModel
+from .services.model_load_balancer import ModelLoadBalancer
+from .vectorstores.milvus import SchemaMilvus, VDBService
+
+__all__ = [
+    "GeminiChatModel",
+    "ModelLoadBalancer",
+    "SchemaMilvus",
+    "VDBService"
+]

crewplus/callbacks/__init__.py

@@ -0,0 +1 @@
+# This file makes the 'callbacks' directory a Python package.

crewplus/callbacks/async_langfuse_handler.py

@@ -0,0 +1,166 @@
+# File: crewplus/callbacks/async_langfuse_handler.py
+import asyncio
+import contextvars
+from contextlib import contextmanager
+from typing import Any, Dict, List, Union, Optional, Sequence
+from uuid import UUID
+
+try:
+    from langfuse.langchain import CallbackHandler as LangfuseCallbackHandler
+    from langchain_core.callbacks import AsyncCallbackHandler
+    from langchain_core.outputs import LLMResult, ChatGeneration
+    from langchain_core.messages import BaseMessage
+    from langchain.schema.agent import AgentAction, AgentFinish
+    from langchain.schema.document import Document
+    LANGFUSE_AVAILABLE = True
+except ImportError:
+    LANGFUSE_AVAILABLE = False
+    LangfuseCallbackHandler = None
+    AsyncCallbackHandler = object
+    # Define dummy types if langchain is not available
+    LLMResult = object
+    BaseMessage = object
+    AgentAction = object
+    AgentFinish = object
+    Document = object
+
+
+_ASYNC_CONTEXT_TOKEN = "in_async_context"
+in_async_context = contextvars.ContextVar(_ASYNC_CONTEXT_TOKEN, default=False)
+
+@contextmanager
+def async_context():
+    """A context manager to signal that we are in an async execution context."""
+    token = in_async_context.set(True)
+    try:
+        yield
+    finally:
+        in_async_context.reset(token)
+
+class AsyncLangfuseCallbackHandler(AsyncCallbackHandler):
+    """
+    Wraps the synchronous LangfuseCallbackHandler to make it fully compatible with
+    LangChain's async methods by handling all relevant events.
+    """
+    def __init__(self, sync_handler: Optional[LangfuseCallbackHandler] = None, *args: Any, **kwargs: Any):
+        if not LANGFUSE_AVAILABLE:
+            raise ImportError("Langfuse is not available. Please install it with 'pip install langfuse'")
+        
+        if sync_handler:
+            self.sync_handler = sync_handler
+        else:
+            self.sync_handler = LangfuseCallbackHandler(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.sync_handler, name)
+
+    # LLM Events
+    async def on_llm_start(
+        self, serialized: Dict[str, Any], prompts: List[str], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> None:
+        corrected_prompts = prompts if isinstance(prompts, list) else [prompts]
+        await asyncio.to_thread(
+            self.sync_handler.on_llm_start, serialized, corrected_prompts, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_chat_model_start(
+        self, serialized: Dict[str, Any], messages: List[List[BaseMessage]], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_chat_model_start, serialized, messages, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_llm_end(
+        self, response: LLMResult, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync_handler.on_llm_end, response, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_llm_error(
+        self, error: Union[Exception, KeyboardInterrupt], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync_handler.on_llm_error, error, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    # Chain Events
+    async def on_chain_start(
+        self, serialized: Dict[str, Any], inputs: Dict[str, Any], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_chain_start, serialized, inputs, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_chain_end(
+        self, outputs: Dict[str, Any], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_chain_end, outputs, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_chain_error(
+        self, error: Union[Exception, KeyboardInterrupt], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_chain_error, error, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    # Tool Events
+    async def on_tool_start(
+        self, serialized: Dict[str, Any], input_str: str, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_tool_start, serialized, input_str, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_tool_end(
+        self, output: str, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_tool_end, output, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_tool_error(
+        self, error: Union[Exception, KeyboardInterrupt], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_tool_error, error, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+        
+    # Retriever Events
+    async def on_retriever_start(
+        self, serialized: Dict[str, Any], query: str, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_retriever_start, serialized, query, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_retriever_end(
+        self, documents: Sequence[Document], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_retriever_end, documents, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_retriever_error(
+        self, error: Union[Exception, KeyboardInterrupt], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_retriever_error, error, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+        
+    # Agent Events
+    async def on_agent_action(
+        self, action: AgentAction, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_agent_action, action, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    async def on_agent_finish(
+        self, finish: AgentFinish, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any
+    ) -> Any:
+        await asyncio.to_thread(
+            self.sync_handler.on_agent_finish, finish, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )

crewplus/services/__init__.py

@@ -0,0 +1,21 @@
+from .gemini_chat_model import GeminiChatModel
+from .init_services import init_load_balancer, get_model_balancer
+from .model_load_balancer import ModelLoadBalancer
+from .azure_chat_model import TracedAzureChatOpenAI
+from .feedback_manager import LangfuseFeedbackManager
+from .schemas.feedback import FeedbackIn, FeedbackUpdate, FeedbackOut
+from .tracing_manager import TracingManager, TracingContext
+
+__all__ = [
+    "GeminiChatModel", 
+    "init_load_balancer", 
+    "get_model_balancer", 
+    "ModelLoadBalancer", 
+    "TracedAzureChatOpenAI",
+    "LangfuseFeedbackManager",
+    "FeedbackIn",
+    "FeedbackUpdate",
+    "FeedbackOut",
+    "TracingManager",
+    "TracingContext"
+]

crewplus/services/azure_chat_model.py

@@ -0,0 +1,145 @@
+import os
+import logging
+from typing import Any, Optional
+
+from langchain_openai.chat_models.azure import AzureChatOpenAI
+from pydantic import Field
+from .tracing_manager import TracingManager, TracingContext
+
+class TracedAzureChatOpenAI(AzureChatOpenAI):
+    """
+    Wrapper for AzureChatOpenAI that integrates with tracing services like Langfuse.
+    
+    This class automatically handles callback integration, making it easier
+    to trace and debug your interactions with the Azure OpenAI service.
+
+    **Tracing Integration (e.g., Langfuse):**
+    Tracing is automatically enabled when the respective environment variables are set.
+    For Langfuse:
+    - LANGFUSE_PUBLIC_KEY: Your Langfuse public key
+    - LANGFUSE_SECRET_KEY: Your Langfuse secret key  
+    - LANGFUSE_HOST: Langfuse host URL (optional, defaults to https://cloud.langfuse.com)
+    
+    You can explicitly control this with the `enable_tracing` parameter or disable
+    it for specific calls by adding `{"metadata": {"tracing_disabled": True}}`
+    to the `config` argument.
+
+    Attributes:
+        logger (Optional[logging.Logger]): An optional logger instance.
+        enable_tracing (Optional[bool]): Enable/disable tracing (auto-detect if None).
+
+    Example:
+        .. code-block:: python
+
+            # Set Langfuse environment variables (optional)
+            import os
+            os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
+            os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
+
+            from crewplus.services.azure_chat_model import TracedAzureChatOpenAI
+            from langchain_core.messages import HumanMessage
+
+            # Initialize the model
+            model = TracedAzureChatOpenAI(
+                azure_deployment="your-deployment",
+                api_version="2024-05-01-preview",
+            )
+
+            # --- Text-only usage (automatically traced if env vars set) ---
+            response = model.invoke("Hello, how are you?")
+            print("Text response:", response.content)
+
+            # --- Tracing with session/user tracking (for Langfuse) ---
+            response = model.invoke(
+                "What is AI?",
+                config={
+                    "metadata": {
+                        "langfuse_session_id": "chat-session-123",
+                        "user_id": "user-456"
+                    }
+                }
+            )
+            
+            # --- Disable tracing for a specific call ---
+            response = model.invoke(
+                "Hello without tracing",
+                config={"metadata": {"tracing_disabled": True}}
+            )
+
+            # --- Asynchronous Streaming Usage ---
+            import asyncio
+            from langchain_core.messages import HumanMessage
+
+            async def main():
+                messages = [HumanMessage(content="Tell me a short story about a brave robot.")]
+                print("\nAsync Streaming response:")
+                async for chunk in model.astream(messages):
+                    print(chunk.content, end="", flush=True)
+                print()
+
+            # In a real application, you would run this with:
+            # asyncio.run(main())
+    """
+    logger: Optional[logging.Logger] = Field(default=None, description="Optional logger instance", exclude=True)
+    enable_tracing: Optional[bool] = Field(default=None, description="Enable tracing (auto-detect if None)")
+    
+    _tracing_manager: Optional[TracingManager] = None
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        
+        # Initialize logger
+        if self.logger is None:
+            self.logger = logging.getLogger(f"{self.__class__.__module__}.{self.__class__.__name__}")
+            if not self.logger.handlers:
+                self.logger.addHandler(logging.StreamHandler())
+                self.logger.setLevel(logging.INFO)
+        
+        self._tracing_manager = TracingManager(self)
+
+    def get_model_identifier(self) -> str:
+        """Return a string identifying this model for tracing and logging."""
+        return f"{self.__class__.__name__} (deployment='{self.deployment_name}')"
+
+    def _prepare_stream_kwargs(self, kwargs: Optional[dict], *, async_mode: bool) -> dict:
+        """
+        Inject stream_options for Langfuse usage tracking only when streaming is supported.
+        Avoids passing illegal stream_options to non-streaming requests (which causes 400s).
+        """
+        final_kwargs = dict(kwargs or {})
+
+        probe_kwargs = {**final_kwargs, "stream": final_kwargs.get("stream", True)}
+
+        # Older or mocked BaseChatModel variants might not expose _should_stream;
+        # if AttributeError is raised, default to previous behavior (assume streaming)
+        # so Langfuse usage tracking remains enabled instead of silently disabling it.        
+        try:
+            will_stream = self._should_stream(async_api=async_mode, **probe_kwargs)
+        except AttributeError:
+            will_stream = True
+
+        if will_stream:
+            stream_options = dict(final_kwargs.get("stream_options") or {})
+            stream_options["include_usage"] = True
+            final_kwargs["stream_options"] = stream_options
+
+        return final_kwargs
+
+    def invoke(self, input, config=None, **kwargs):
+        config = self._tracing_manager.add_sync_callbacks_to_config(config)
+        return super().invoke(input, config=config, **kwargs)
+
+    async def ainvoke(self, input, config=None, **kwargs):
+        config = self._tracing_manager.add_async_callbacks_to_config(config)
+        return await super().ainvoke(input, config=config, **kwargs)
+
+    def stream(self, input, config=None, **kwargs):
+        kwargs = self._prepare_stream_kwargs(kwargs, async_mode=False)
+        config = self._tracing_manager.add_sync_callbacks_to_config(config)
+        yield from super().stream(input, config=config, **kwargs)
+
+    async def astream(self, input, config=None, **kwargs) :
+        kwargs = self._prepare_stream_kwargs(kwargs, async_mode=True)
+        config = self._tracing_manager.add_async_callbacks_to_config(config)
+        async for chunk in super().astream(input, config=config, **kwargs):
+            yield chunk

crewplus/services/feedback.md

@@ -0,0 +1,55 @@
+# Feedback Management with Langfuse
+
+This document outlines the design and implementation of the Langsmith-style feedback system using Langfuse as the backend.
+
+## Design Approach: Parent Observation for Feedback Groups
+
+To replicate the grouped feedback functionality seen in Langsmith, we use Langfuse's hierarchical tracing structure. This approach is called the "Parent Observation" model.
+
+-   **Feedback Group**: A batch of feedback items submitted together (e.g., a user rating multiple aspects of a response) is represented as a single **`Span`** (also called an Observation) in Langfuse. This `Span` acts as a container for the group.
+-   **Group-Level Data**: All metadata that applies to the entire group, such as `correction` data or a unique `feedback_group_id`, is stored in the `metadata` of this parent `Span`.
+-   **Individual Feedback**: Each individual feedback item (e.g., "helpfulness: 0.9", "safety: true") is represented as a **`Score`** object.
+-   **Linking**: Crucially, each `Score` is linked to the parent `Span` via its `observation_id`. This creates the hierarchy that is visible in the Langfuse UI.
+
+This design provides a clean UI representation and a semantically correct data model.
+
+### Example
+
+A user submits feedback for a chatbot response (`run_id: "trace-123"`):
+-   **Helpfulness**: 9/10
+-   **Safety**: Safe (True)
+-   **Correction**: The answer should have included details about X.
+
+This is modeled in Langfuse as:
+
+1.  A **`Span`** is created in trace `trace-123`.
+    -   `name`: "user-feedback-group"
+    -   `metadata`: `{ "feedback_group_id": "fg-abc", "correction": { "expected": "..." } }`
+    -   This span gets a unique `observation_id`, e.g., `"obs-xyz"`.
+2.  Two **`Score`** objects are created:
+    -   Score 1:
+        -   `name`: "helpfulness"
+        -   `value`: `0.9`
+        -   `trace_id`: "trace-123"
+        -   `observation_id`: `"obs-xyz"` (links to the parent span)
+    -   Score 2:
+        -   `name`: "safety"
+        -   `value`: `1.0` (boolean `True` is converted)
+        -   `trace_id`: "trace-123"
+        -   `observation_id`: `"obs-xyz"` (links to the parent span)
+
+## Data Mapping: Langfuse API to `FeedbackOut` Schema
+
+The `read_feedback` method in `LangfuseFeedbackManager` fetches data from multiple Langfuse objects and combines them into a single, consistent `FeedbackOut` Pydantic model.
+
+| `FeedbackOut` Field   | Source of Data                                   | Example Value                                  |
+| --------------------- | ------------------------------------------------ | ---------------------------------------------- |
+| `feedback_id`         | `score.id`                                       | `'sc-12345'`                                   |
+| `run_id`              | `score.trace_id`                                 | `'tr-abcde'`                                   |
+| `key`                 | `score.name`                                     | `'helpfulness'`                                |
+| `score`               | `score.value`                                    | `0.9`                                          |
+| `value`               | `score.metadata.get('value_dict')` or `score.value` | `{'direction': 'up'}` or `'up'`                |
+| `comment`             | `score.comment`                                  | `'Very helpful.'`                              |
+| `created_at`          | `score.timestamp`                                | `datetime.datetime(...)`                       |
+| `correction`          | `parent_observation.metadata.get('correction')`  | `{'expected': 'A perfect answer.'}`            |
+| `feedback_group_id`   | `parent_observation.metadata.get('feedback_group_id')` | `'fg-xyz-789'`                                 |

crewplus/services/feedback_manager.py

@@ -0,0 +1,267 @@
+import logging
+from typing import Optional, List, Union, Dict, Any
+from uuid import UUID, uuid4
+import datetime
+
+from langfuse import Langfuse
+from langfuse.types import TraceContext
+from .schemas.feedback import FeedbackIn, FeedbackUpdate, FeedbackOut
+
+logger = logging.getLogger(__name__)
+
+class LangfuseFeedbackManager:
+    """
+    Manages CRUD operations for Langsmith-style feedback using Langfuse as the backend.
+    
+    This manager uses the "Parent Observation" approach, where a batch of feedback
+    is represented by a parent Span, and each individual feedback item is a Score
+    attached to that Span. It is designed to work with an existing trace (run).
+    """
+
+    def __init__(self, langfuse_client: Langfuse):
+        """
+        Initializes the feedback manager with a Langfuse client instance.
+
+        Args:
+            langfuse_client: An initialized Langfuse client.
+        """
+        if not langfuse_client:
+            raise ValueError("A valid Langfuse client instance is required.")
+        self.client = langfuse_client
+
+    def read_feedback(self, feedback_id: str) -> Optional[FeedbackOut]:
+        """
+        Reads a single feedback item (a Score) and enriches it with data
+        from its parent observation (the feedback group).
+
+        Args:
+            feedback_id: The unique ID of the feedback item (score).
+
+        Returns:
+            A FeedbackOut object containing the full context, or None if not found.
+        """
+        try:
+            # Step 1: Fetch the score itself using the correct v2 client and method.
+            # The get method expects a list of IDs and returns a response object.
+            scores_response = self.client.api.score_v_2.get(score_ids=[feedback_id])
+            if not scores_response or not scores_response.data:
+                logger.warning(f"No score found for feedback_id: {feedback_id}")
+                return None
+            
+            score = scores_response.data[0]
+
+            correction = None
+            feedback_group_id = None
+            value = score.value
+            run_id_to_return = score.trace_id
+
+            # Step 2: Fetch the parent observation to get group context
+            if score.observation_id:
+                parent_obs = self.client.api.observations.get(observation_id=score.observation_id)
+                if parent_obs.metadata:
+                    correction = parent_obs.metadata.get("correction")
+                    feedback_group_id = parent_obs.metadata.get("feedback_group_id")
+                    original_run_id = parent_obs.metadata.get("original_run_id")
+                    if original_run_id:
+                        run_id_to_return = original_run_id
+                
+                # Check if the original value was a dict stored in the score's metadata
+                if score.metadata and "value_dict" in score.metadata:
+                    value = score.metadata["value_dict"]
+
+            # Step 3: Construct the rich FeedbackOut object from the collected data.
+            # This is where the raw data is parsed into your desired schema.
+            return FeedbackOut(
+                feedback_id=score.id,
+                run_id=run_id_to_return,
+                key=score.name,
+                score=score.value,
+                value=value,
+                comment=score.comment,
+                created_at=score.timestamp,
+                correction=correction,
+                feedback_group_id=feedback_group_id,
+            )
+        except Exception:
+            logger.exception("Failed to read feedback with id=%s", feedback_id)
+            return None
+
+    def create_feedback_batch(self, feedbacks: List[FeedbackIn]) -> List[FeedbackOut]:
+        """
+        Creates a group of feedback items under a single parent observation in an existing trace.
+
+        Args:
+            feedbacks: A list of FeedbackIn objects. The `run_id`, `correction`, and 
+                       `feedback_group_id` from the first item are used for the group.
+        
+        Returns:
+            A list of FeedbackOut objects for the created feedback items.
+        """
+        if not feedbacks:
+            return []
+
+        first_item = feedbacks[0]
+        run_id = str(first_item.run_id)
+        # Convert the client's run_id to a deterministic Langfuse trace_id.
+        trace_id = Langfuse.create_trace_id(seed=run_id)
+        feedback_group_id = str(first_item.feedback_group_id or uuid4())
+        
+        group_metadata = {
+            "feedback_group_id": feedback_group_id,
+            "original_run_id": run_id, # Store original run_id for retrieval
+        }
+        if first_item.correction:
+            group_metadata["correction"] = first_item.correction
+
+        try:
+            # Create the parent span within the existing trace to act as the group container.
+            feedback_group_span = self.client.start_span(
+                trace_context=TraceContext(trace_id=trace_id),
+                name="user-feedback-group",
+                metadata=group_metadata,
+                input=[f.dict(exclude_unset=True) for f in feedbacks]
+            )
+            parent_observation_id = feedback_group_span.id
+
+            created_feedbacks = []
+            for item in feedbacks:
+                score_value: Any = item.score if item.score is not None else item.value
+                
+                if isinstance(score_value, bool):
+                    score_value = 1.0 if score_value else 0.0
+                
+                score_metadata = None
+                value_to_return = score_value
+                if isinstance(score_value, dict):
+                    score_metadata = {"value_dict": score_value}
+                    value_to_return = score_value
+                    # Langfuse score `value` must be string or float. Set to neutral.
+                    score_value = 0 
+
+                if score_value is not None:
+                    # Manually create a score ID to include it in the returned object.
+                    score_id = self.client._create_observation_id()
+                    self.client.create_score(
+                        score_id=score_id,
+                        name=item.key,
+                        value=score_value,
+                        trace_id=trace_id,
+                        observation_id=parent_observation_id,
+                        comment=item.comment,
+                        metadata=score_metadata,
+                    )
+                    
+                    feedback_out = FeedbackOut(
+                        feedback_id=score_id,
+                        run_id=run_id,
+                        key=item.key,
+                        score=score_value,
+                        value=value_to_return,
+                        comment=item.comment,
+                        created_at=datetime.datetime.now(datetime.timezone.utc),
+                        correction=group_metadata.get("correction"),
+                        feedback_group_id=feedback_group_id,
+                    )
+                    created_feedbacks.append(feedback_out)
+            
+            feedback_group_span.end()
+            self.client.flush()
+            return created_feedbacks
+        except Exception:
+            logger.exception("Failed to create feedback batch for run_id=%s", run_id)
+            return []
+
+    def get_feedback_by_group_id(self, run_id: str, feedback_group_id: str) -> List[Dict[str, Any]]:
+        """
+        Retrieves all scores for a given feedback group ID within a trace.
+
+        Args:
+            run_id: The application-specific run ID, which will be converted to a trace ID.
+            feedback_group_id: The ID of the feedback group.
+        
+        Returns:
+            A list of score dictionaries.
+        """
+        try:
+            trace_id = Langfuse.create_trace_id(seed=run_id)
+            full_trace = self.client.api.trace.get(trace_id=trace_id)
+            
+            parent_obs = next(
+                (obs for obs in full_trace.observations 
+                 if obs.metadata and obs.metadata.get("feedback_group_id") == feedback_group_id),
+                None
+            )
+            
+            if not parent_obs:
+                return []
+
+            return [
+                score.dict() for score in full_trace.scores 
+                if score.observation_id == parent_obs.id
+            ]
+        except Exception:
+            logger.exception(f"Error getting feedback for run_id {run_id} and group {feedback_group_id}")
+            return []
+
+    def delete_feedback(self, feedback_id: str) -> bool:
+        """Deletes a single feedback item (a Score)."""
+        try:
+            self.client.api.score.delete(score_id=feedback_id)
+            # Flush immediately to minimize the non-atomic window.
+            self.client.flush()
+            return True
+        except Exception:
+            logger.exception("Failed to delete feedback with id=%s", feedback_id)
+            return False
+            
+    def update_feedback(self, feedback_id: str, update_data: FeedbackUpdate) -> bool:
+        """
+        Updates a feedback item (Score).
+
+        ATTENTION: Langfuse does not support native updates for scores. This method
+        simulates an update by DELETING the old score and CREATING a new one with the
+        same ID to preserve client-side consistency.
+
+        WARNING: This operation is not atomic. There is a small time window between
+        deletion and creation where a read for this feedback ID will fail.
+
+        Note: Updates to `correction` are ignored by this method, as `correction` is a 
+        group-level attribute on the parent observation, which cannot be modified
+        after creation via the SDK.
+        """
+        try:
+            scores_response = self.client.api.score_v_2.get(score_ids=[feedback_id])
+            if not scores_response or not scores_response.data:
+                logger.warning(f"Cannot update. No score found for feedback_id: {feedback_id}")
+                return False
+            score_to_update = scores_response.data[0]
+
+            if update_data.correction is not None:
+                logger.warning(
+                    "Updating 'correction' on an individual feedback item is not supported "
+                    "as it's a group-level attribute. This field will be ignored."
+                )
+
+            # Preserve the ID by deleting and then recreating the score.
+            self.delete_feedback(feedback_id)
+
+            new_val = update_data.score if update_data.score is not None else update_data.value
+            if new_val is None: new_val = score_to_update.value
+            if isinstance(new_val, bool): new_val = 1.0 if new_val else 0.0
+
+            self.client.create_score(
+                score_id=feedback_id,  # Re-use the original score ID
+                name=score_to_update.name,
+                value=new_val,
+                trace_id=score_to_update.trace_id,
+                observation_id=score_to_update.observation_id,
+                comment=update_data.comment or score_to_update.comment,
+                metadata=score_to_update.metadata
+            )
+            # Flush immediately to minimize the non-atomic window.
+            self.client.flush()
+            
+            return True
+        except Exception:
+            logger.exception("Failed to update feedback for id=%s", feedback_id)
+            return False