feedback-manager 0.1.0__py3-none-any.whl

feedback_manager/__init__.py

@@ -0,0 +1,75 @@
+"""FeedbackManager: feedback infrastructure for LangChain/LangGraph applications.
+
+FeedbackManager captures, correlates, persists, routes, and manages the
+lifecycle of feedback generated during or around agent execution. It is a
+library, not a runtime: LangGraph/LangChain continue to own execution,
+state, checkpoints, interrupts, and streaming.
+
+The public surface is intentionally small. Most applications only need::
+
+    from feedback_manager import FeedbackManager, FeedbackSource, FeedbackCategory, FeedbackTarget, FeedbackTargetType
+
+    manager = FeedbackManager()
+    event = await manager.submit(
+        source=FeedbackSource.HUMAN,
+        category=FeedbackCategory.CORRECTION,
+        target=FeedbackTarget(type=FeedbackTargetType.GENERATION, id="gen-1"),
+        payload={"corrected_text": "..."},
+    )
+
+See ``docs/`` for the full architecture, extension points, and framework
+integrations (``feedback_manager.integrations``).
+"""
+
+from feedback_manager.api.manager import FeedbackManager
+from feedback_manager.api.queries import FeedbackQuery
+from feedback_manager.api.subscription import Subscription
+from feedback_manager.core.categories import FeedbackCategory
+from feedback_manager.core.context import CorrelationContext, ExecutionContext
+from feedback_manager.core.events import FeedbackEvent
+from feedback_manager.core.lifecycle import validate_transition
+from feedback_manager.core.provenance import FeedbackProvenanceReference
+from feedback_manager.core.sources import FeedbackSource
+from feedback_manager.core.status import FeedbackStatus
+from feedback_manager.core.targets import FeedbackTarget, FeedbackTargetType
+from feedback_manager.errors.exceptions import (
+    FeedbackConfigurationError,
+    FeedbackCorrelationError,
+    FeedbackHandlerError,
+    FeedbackLifecycleError,
+    FeedbackManagerError,
+    FeedbackNotFoundError,
+    FeedbackRoutingError,
+    FeedbackSerializationError,
+    FeedbackStoreError,
+    FeedbackValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CorrelationContext",
+    "ExecutionContext",
+    "FeedbackCategory",
+    "FeedbackConfigurationError",
+    "FeedbackCorrelationError",
+    "FeedbackEvent",
+    "FeedbackHandlerError",
+    "FeedbackLifecycleError",
+    "FeedbackManager",
+    "FeedbackManagerError",
+    "FeedbackNotFoundError",
+    "FeedbackProvenanceReference",
+    "FeedbackQuery",
+    "FeedbackRoutingError",
+    "FeedbackSerializationError",
+    "FeedbackSource",
+    "FeedbackStatus",
+    "FeedbackStoreError",
+    "FeedbackTarget",
+    "FeedbackTargetType",
+    "FeedbackValidationError",
+    "Subscription",
+    "__version__",
+    "validate_transition",
+]

feedback_manager/_logging.py

@@ -0,0 +1,31 @@
+"""Internal ``structlog`` wiring shared by the bundled logging sinks/handlers.
+
+Library code must not call ``structlog.configure()`` globally -- that is an
+application-level decision. Each logger created here instead wraps the
+equivalent stdlib :class:`logging.Logger` directly via
+:func:`structlog.wrap_logger`, so host applications that configure Python's
+standard ``logging`` module (handlers, filters, levels, ``caplog`` in tests,
+...) continue to see feedback-manager's structured log output without any
+extra wiring.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import structlog
+
+
+def get_logger(name: str) -> Any:
+    """Return a ``structlog`` logger bound to the stdlib logger named ``name``."""
+    return structlog.wrap_logger(
+        logging.getLogger(name),
+        processors=[
+            structlog.stdlib.add_log_level,
+            structlog.processors.KeyValueRenderer(key_order=["event"]),
+        ],
+    )
+
+
+__all__ = ["get_logger"]

feedback_manager/api/__init__.py

@@ -0,0 +1,7 @@
+"""The small, stable public application service."""
+
+from feedback_manager.api.manager import FeedbackManager
+from feedback_manager.api.queries import FeedbackQuery
+from feedback_manager.api.subscription import Subscription
+
+__all__ = ["FeedbackManager", "FeedbackQuery", "Subscription"]

feedback_manager/api/manager.py

@@ -0,0 +1,339 @@
+"""``FeedbackManager``: the small, stable public application service.
+
+This is the single entry point most applications need. It wires together
+the extension points (store, router, correlator, failure policy,
+observability sink) plus provenance from ``langgraph-xai`` via dependency
+injection -- there is no hidden global state, and every
+:class:`FeedbackManager` instance is fully independent of every other one
+(Section 29 of the spec).
+
+Pass your ``langgraph_xai.XAIRuntime`` directly as ``xai_runtime`` and
+``FeedbackManager`` wires up :class:`XAIProvenanceAdapter` automatically
+(``langgraph-xai`` is the mandatory, sole provenance source, so there is
+nothing else to choose between). ``provenance_adapter`` remains available
+for tests or advanced call sites that already hold a constructed adapter.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+from uuid import UUID
+
+from langgraph_xai import XAIRuntime
+
+from feedback_manager.api.queries import FeedbackQuery
+from feedback_manager.api.subscription import Subscription
+from feedback_manager.contracts.correlator import FeedbackCorrelator
+from feedback_manager.contracts.handler import FeedbackContext
+from feedback_manager.contracts.policy import FeedbackLifecyclePolicy, FeedbackPolicy
+from feedback_manager.contracts.router import FeedbackRouter
+from feedback_manager.contracts.store import FeedbackStore
+from feedback_manager.contracts.subscriber import FeedbackSubscriber
+from feedback_manager.core.categories import FeedbackCategory
+from feedback_manager.core.context import ExecutionContext
+from feedback_manager.core.events import FeedbackEvent
+from feedback_manager.core.sources import FeedbackSource
+from feedback_manager.core.status import FeedbackStatus
+from feedback_manager.core.targets import FeedbackTarget
+from feedback_manager.correlation.correlator import DefaultFeedbackCorrelator
+from feedback_manager.errors import FeedbackNotFoundError, FeedbackStoreError
+from feedback_manager.integrations.xai.adapter import XAIProvenanceAdapter
+from feedback_manager.observability.hooks import (
+    FEEDBACK_ACKNOWLEDGED,
+    FEEDBACK_CREATED,
+    FEEDBACK_HANDLED,
+    FEEDBACK_RECEIVED,
+    FEEDBACK_RESOLVED,
+    FEEDBACK_ROUTED,
+    LoggingObservabilitySink,
+    ObservabilityEvent,
+    ObservabilitySink,
+)
+from feedback_manager.policies.failure import FailurePolicy, FeedbackStage
+from feedback_manager.routing.default_router import DefaultFeedbackRouter
+from feedback_manager.storage.memory import InMemoryFeedbackStore
+
+_STATUS_EVENT_NAMES: dict[FeedbackStatus, str] = {
+    FeedbackStatus.ACKNOWLEDGED: FEEDBACK_ACKNOWLEDGED,
+    FeedbackStatus.HANDLED: FEEDBACK_HANDLED,
+    FeedbackStatus.RESOLVED: FEEDBACK_RESOLVED,
+    FeedbackStatus.REJECTED: FEEDBACK_RESOLVED,
+    FeedbackStatus.CANCELLED: FEEDBACK_RESOLVED,
+    FeedbackStatus.EXPIRED: FEEDBACK_RESOLVED,
+}
+
+
+class FeedbackManager:
+    """Capture, correlate, persist, route, and resolve feedback.
+
+    Every dependency is optional and defaults to an in-memory/no-op
+    implementation, so ``FeedbackManager()`` is immediately usable; pass in
+    your own :class:`~feedback_manager.contracts.store.FeedbackStore`,
+    :class:`~feedback_manager.contracts.router.FeedbackRouter`, etc. to
+    plug in production infrastructure without modifying this class.
+
+    For provenance, pass your own ``langgraph_xai.XAIRuntime`` as
+    ``xai_runtime`` -- ``FeedbackManager`` builds the
+    :class:`~feedback_manager.integrations.xai.adapter.XAIProvenanceAdapter`
+    for you automatically.
+    """
+
+    def __init__(
+        self,
+        *,
+        store: FeedbackStore | None = None,
+        router: FeedbackRouter | None = None,
+        correlator: FeedbackCorrelator | None = None,
+        xai_runtime: XAIRuntime | None = None,
+        provenance_adapter: XAIProvenanceAdapter | None = None,
+        lifecycle_policy: FeedbackLifecyclePolicy | None = None,
+        redaction_policy: FeedbackPolicy | None = None,
+        failure_policy: FailurePolicy | None = None,
+        observability_sink: ObservabilitySink | None = None,
+    ) -> None:
+        if provenance_adapter is not None and xai_runtime is not None:
+            raise ValueError("pass either xai_runtime or provenance_adapter, not both")
+        self._store: FeedbackStore = store if store is not None else InMemoryFeedbackStore()
+        self._router: FeedbackRouter = router if router is not None else DefaultFeedbackRouter()
+        self._correlator: FeedbackCorrelator = (
+            correlator if correlator is not None else DefaultFeedbackCorrelator()
+        )
+        if provenance_adapter is not None:
+            self._provenance_adapter: XAIProvenanceAdapter | None = provenance_adapter
+        elif xai_runtime is not None:
+            self._provenance_adapter = XAIProvenanceAdapter(xai_runtime)
+        else:
+            self._provenance_adapter = None
+        self._lifecycle_policy = lifecycle_policy
+        self._redaction_policy = redaction_policy
+        self._failure_policy = failure_policy if failure_policy is not None else FailurePolicy()
+        self._observability_sink: ObservabilitySink = (
+            observability_sink if observability_sink is not None else LoggingObservabilitySink()
+        )
+        self._subscribers: list[FeedbackSubscriber] = []
+        self._stream_queues: list[asyncio.Queue[FeedbackEvent]] = []
+
+    # -- submission -----------------------------------------------------
+
+    async def submit(
+        self,
+        *,
+        source: FeedbackSource | str,
+        category: FeedbackCategory | str,
+        target: FeedbackTarget,
+        payload: dict[str, Any] | None = None,
+        execution_context: ExecutionContext | None = None,
+        idempotency_key: str | None = None,
+        feedback_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> FeedbackEvent:
+        """Submit a new piece of feedback and run it through the pipeline.
+
+        Pipeline: build -> correlate -> resolve provenance (best-effort) ->
+        persist -> transition to ``RECEIVED`` -> notify subscribers -> route
+        to handlers (best-effort, isolated per handler).
+        """
+        event = FeedbackEvent(
+            source=FeedbackSource(source),
+            category=FeedbackCategory(category),
+            target=target,
+            payload=payload or {},
+            execution_context=execution_context,
+            idempotency_key=idempotency_key,
+            feedback_type=feedback_type,
+            metadata=metadata or {},
+        )
+        if self._redaction_policy is not None:
+            event = self._redaction_policy.apply(event)
+
+        correlation = await self._correlator.correlate(event, execution_context)
+        event = event.with_correlation(correlation)
+
+        if self._provenance_adapter is not None:
+            provenance_adapter = self._provenance_adapter
+            provenance = await self._failure_policy.run_stage(
+                FeedbackStage.PROVENANCE, lambda: provenance_adapter.resolve(correlation)
+            )
+            if provenance is not None:
+                event = event.with_provenance(provenance)
+
+        created = await self._failure_policy.run_stage(
+            FeedbackStage.STORE, lambda: self._store.create(event)
+        )
+        if created is None:
+            raise FeedbackStoreError(
+                "failed to persist feedback event", feedback_id=event.feedback_id
+            )
+        if created.feedback_id != event.feedback_id:
+            # Idempotency-key hit: an event with this key already existed and may
+            # already be anywhere in its lifecycle. Submission is a no-op that
+            # simply returns the current state, per Section 28 of the spec.
+            return created
+        self._emit(FEEDBACK_CREATED, created)
+
+        received = await self._failure_policy.run_stage(
+            FeedbackStage.STORE,
+            lambda: self._store.transition(created.feedback_id, FeedbackStatus.RECEIVED),
+        )
+        if received is None:
+            raise FeedbackStoreError(
+                "failed to transition feedback to RECEIVED", feedback_id=created.feedback_id
+            )
+        self._emit(FEEDBACK_RECEIVED, received)
+        await self._notify_subscribers(received)
+        await self._route(received)
+        return received
+
+    async def _route(self, feedback: FeedbackEvent) -> None:
+        handlers = await self._failure_policy.run_stage(
+            FeedbackStage.ROUTING, lambda: self._router.route(feedback)
+        )
+        if not handlers:
+            return
+        context = FeedbackContext(correlation=feedback.correlation)
+        for handler in handlers:
+
+            async def _run(handler: Any = handler) -> None:
+                await handler.handle(feedback, context)
+
+            await self._failure_policy.run_stage(FeedbackStage.HANDLER, _run)
+        self._emit(FEEDBACK_ROUTED, feedback, attributes={"handler_count": len(handlers)})
+
+    # -- lifecycle --------------------------------------------------------
+
+    async def acknowledge(self, feedback_id: UUID) -> FeedbackEvent:
+        """Transition feedback to ``ACKNOWLEDGED`` (a consumer has seen it)."""
+        return await self._transition(feedback_id, FeedbackStatus.ACKNOWLEDGED)
+
+    async def mark_handled(self, feedback_id: UUID) -> FeedbackEvent:
+        """Transition feedback to ``HANDLED`` (processing is complete, pending resolution)."""
+        return await self._transition(feedback_id, FeedbackStatus.HANDLED)
+
+    async def resolve(
+        self, feedback_id: UUID, *, resolution: dict[str, Any] | None = None
+    ) -> FeedbackEvent:
+        """Transition feedback to the terminal ``RESOLVED`` state."""
+        return await self._transition(feedback_id, FeedbackStatus.RESOLVED, resolution=resolution)
+
+    async def reject(self, feedback_id: UUID, *, reason: str | None = None) -> FeedbackEvent:
+        """Transition feedback to the terminal ``REJECTED`` state."""
+        return await self._transition(
+            feedback_id, FeedbackStatus.REJECTED, resolution={"reason": reason} if reason else None
+        )
+
+    async def cancel(self, feedback_id: UUID, *, reason: str | None = None) -> FeedbackEvent:
+        """Transition feedback to the terminal ``CANCELLED`` state."""
+        return await self._transition(
+            feedback_id, FeedbackStatus.CANCELLED, resolution={"reason": reason} if reason else None
+        )
+
+    async def expire(self, feedback_id: UUID) -> FeedbackEvent:
+        """Transition feedback to the terminal ``EXPIRED`` state."""
+        return await self._transition(feedback_id, FeedbackStatus.EXPIRED)
+
+    async def _transition(
+        self,
+        feedback_id: UUID,
+        status: FeedbackStatus,
+        *,
+        resolution: dict[str, Any] | None = None,
+    ) -> FeedbackEvent:
+        current = await self._store.get(feedback_id)
+        if current is None:
+            raise FeedbackNotFoundError("unknown feedback id", feedback_id=feedback_id)
+        if self._lifecycle_policy is not None:
+            self._lifecycle_policy.authorize_transition(current, status)
+        if resolution:
+            merged = current.model_copy(
+                update={"metadata": {**current.metadata, "resolution": resolution}}
+            )
+            current = await self._failure_policy.run_stage(
+                FeedbackStage.STORE, lambda: self._store.update(merged)
+            )
+            if current is None:
+                raise FeedbackStoreError(
+                    "failed to persist resolution metadata", feedback_id=feedback_id
+                )
+
+        updated = await self._failure_policy.run_stage(
+            FeedbackStage.STORE, lambda: self._store.transition(feedback_id, status)
+        )
+        if updated is None:
+            raise FeedbackStoreError(
+                "failed to persist lifecycle transition", feedback_id=feedback_id
+            )
+        self._emit(_STATUS_EVENT_NAMES.get(status, FEEDBACK_HANDLED), updated)
+        await self._notify_subscribers(updated)
+        return updated
+
+    # -- retrieval --------------------------------------------------------
+
+    async def get(self, feedback_id: UUID) -> FeedbackEvent | None:
+        """Pull-based retrieval of a single feedback event."""
+        return await self._store.get(feedback_id)
+
+    async def query(self, query: FeedbackQuery) -> Sequence[FeedbackEvent]:
+        """Pull-based retrieval of every feedback event matching ``query``."""
+        return await self._store.query(query)
+
+    async def list(self) -> Sequence[FeedbackEvent]:
+        """Pull-based retrieval of every stored feedback event."""
+        return await self._store.list()
+
+    # -- subscriptions ----------------------------------------------------
+
+    def subscribe(self, subscriber: FeedbackSubscriber) -> Subscription:
+        """Register a push-based subscriber, notified on every create/transition."""
+        self._subscribers.append(subscriber)
+
+        def _cancel() -> None:
+            if subscriber in self._subscribers:
+                self._subscribers.remove(subscriber)
+
+        return Subscription(_cancel)
+
+    async def stream(self, query: FeedbackQuery | None = None) -> AsyncIterator[FeedbackEvent]:
+        """Stream feedback events (optionally filtered) as they occur."""
+        queue: asyncio.Queue[FeedbackEvent] = asyncio.Queue()
+        self._stream_queues.append(queue)
+        try:
+            while True:
+                event = await queue.get()
+                if query is None or query.matches(event):
+                    yield event
+        finally:
+            if queue in self._stream_queues:
+                self._stream_queues.remove(queue)
+
+    async def _notify_subscribers(self, event: FeedbackEvent) -> None:
+        for subscriber in list(self._subscribers):
+
+            async def _notify(subscriber: FeedbackSubscriber = subscriber) -> None:
+                await subscriber(event)
+
+            await self._failure_policy.run_stage(FeedbackStage.SUBSCRIBER, _notify)
+        for queue in list(self._stream_queues):
+            queue.put_nowait(event)
+
+    # -- observability ----------------------------------------------------
+
+    def _emit(
+        self, name: str, event: FeedbackEvent, *, attributes: dict[str, Any] | None = None
+    ) -> None:
+        self._observability_sink.emit(
+            ObservabilityEvent(
+                name=name,
+                feedback_id=event.feedback_id,
+                attributes={
+                    "source": str(event.source),
+                    "category": str(event.category),
+                    "status": str(event.status),
+                    **(attributes or {}),
+                },
+            )
+        )
+
+
+__all__ = ["FeedbackManager"]

feedback_manager/api/queries.py

@@ -0,0 +1,11 @@
+"""Feedback query re-export.
+
+``FeedbackQuery`` is defined alongside the :class:`FeedbackStore` contract
+(:mod:`feedback_manager.contracts.store`) since the two are tightly
+coupled, but it is part of the public application-facing API, so it is
+re-exported here as well.
+"""
+
+from feedback_manager.contracts.store import FeedbackQuery
+
+__all__ = ["FeedbackQuery"]

feedback_manager/api/subscription.py

@@ -0,0 +1,27 @@
+"""Subscription handle returned by :meth:`FeedbackManager.subscribe`."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Subscription:
+    """A handle that unsubscribes a :class:`FeedbackSubscriber` when cancelled."""
+
+    _cancel: Callable[[], None]
+    _active: bool = True
+
+    def cancel(self) -> None:
+        """Stop receiving further feedback notifications."""
+        if self._active:
+            self._cancel()
+            self._active = False
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+
+__all__ = ["Subscription"]

feedback_manager/contracts/__init__.py

@@ -0,0 +1,32 @@
+"""Extension-point contracts (ABCs and Protocols) for feedback_manager.
+
+See ``docs/architecture/EXTENSIBILITY_MODEL.md`` for the rationale behind
+each ABC vs. Protocol choice.
+"""
+
+from feedback_manager.contracts.correlator import FeedbackCorrelator
+from feedback_manager.contracts.handler import (
+    FeedbackContext,
+    FeedbackHandler,
+    FeedbackHandlerResult,
+)
+from feedback_manager.contracts.policy import FeedbackLifecyclePolicy, FeedbackPolicy
+from feedback_manager.contracts.router import FeedbackRouter
+from feedback_manager.contracts.serializer import DefaultFeedbackSerializer, FeedbackSerializer
+from feedback_manager.contracts.store import FeedbackQuery, FeedbackStore
+from feedback_manager.contracts.subscriber import FeedbackSubscriber
+
+__all__ = [
+    "DefaultFeedbackSerializer",
+    "FeedbackContext",
+    "FeedbackCorrelator",
+    "FeedbackHandler",
+    "FeedbackHandlerResult",
+    "FeedbackLifecyclePolicy",
+    "FeedbackPolicy",
+    "FeedbackQuery",
+    "FeedbackRouter",
+    "FeedbackSerializer",
+    "FeedbackStore",
+    "FeedbackSubscriber",
+]

feedback_manager/contracts/correlator.py

@@ -0,0 +1,20 @@
+"""Structural contract for deriving correlation context at submission time."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from feedback_manager.core.context import CorrelationContext, ExecutionContext
+from feedback_manager.core.events import FeedbackEvent
+
+
+@runtime_checkable
+class FeedbackCorrelator(Protocol):
+    """Derives a :class:`CorrelationContext` for an about-to-be-submitted event."""
+
+    async def correlate(
+        self, feedback: FeedbackEvent, execution_context: ExecutionContext | None
+    ) -> CorrelationContext: ...
+
+
+__all__ = ["FeedbackCorrelator"]

feedback_manager/contracts/handler.py

@@ -0,0 +1,46 @@
+"""Abstract contract for feedback handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from feedback_manager.core.context import CorrelationContext
+from feedback_manager.core.events import FeedbackEvent
+
+
+@dataclass(frozen=True, slots=True)
+class FeedbackContext:
+    """Ambient context passed to a handler alongside the feedback event."""
+
+    correlation: CorrelationContext | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class FeedbackHandlerResult:
+    """The outcome of a single handler invocation."""
+
+    handled: bool
+    detail: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class FeedbackHandler(ABC):
+    """Abstract contract for something that reacts to a :class:`FeedbackEvent`.
+
+    Handlers are independently replaceable and must not raise for
+    business-as-usual outcomes (e.g. "feedback rejected") -- only for
+    genuine handler failures, which the router/manager isolate per the
+    configured :class:`~feedback_manager.policies.failure.FailurePolicy`.
+    """
+
+    @abstractmethod
+    async def handle(
+        self, feedback: FeedbackEvent, context: FeedbackContext
+    ) -> FeedbackHandlerResult:
+        """React to ``feedback`` and report the outcome."""
+
+
+__all__ = ["FeedbackContext", "FeedbackHandler", "FeedbackHandlerResult"]

feedback_manager/contracts/policy.py

@@ -0,0 +1,33 @@
+"""Abstract contracts for feedback and lifecycle policy hooks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from feedback_manager.core.events import FeedbackEvent
+from feedback_manager.core.status import FeedbackStatus
+
+
+class FeedbackLifecyclePolicy(ABC):
+    """Allows application code to add business rules on top of the base state machine.
+
+    The base transition table in :mod:`feedback_manager.core.lifecycle`
+    encodes structural legality only. A ``FeedbackLifecyclePolicy`` can
+    reject an otherwise-legal transition for business reasons (e.g. "only
+    the original requester may resolve their own feedback").
+    """
+
+    @abstractmethod
+    def authorize_transition(self, feedback: FeedbackEvent, target: FeedbackStatus) -> None:
+        """Raise if the transition should not be allowed; return normally otherwise."""
+
+
+class FeedbackPolicy(ABC):
+    """General extension point for redaction/filtering before persistence or serialization."""
+
+    @abstractmethod
+    def apply(self, feedback: FeedbackEvent) -> FeedbackEvent:
+        """Return a (possibly modified) copy of ``feedback``."""
+
+
+__all__ = ["FeedbackLifecyclePolicy", "FeedbackPolicy"]

feedback_manager/contracts/router.py

@@ -0,0 +1,27 @@
+"""Abstract contract for routing feedback events to handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from feedback_manager.contracts.handler import FeedbackHandler
+from feedback_manager.core.events import FeedbackEvent
+
+
+class FeedbackRouter(ABC):
+    """Decides which :class:`FeedbackHandler` instances should see an event.
+
+    Routing may consider any attribute of the event (source, category,
+    target, execution context, lifecycle status, metadata). Implementations
+    must be side-effect free -- routing only *selects* handlers, it does not
+    invoke them (that is the manager's job, so failures in one handler can be
+    isolated from others per the configured failure policy).
+    """
+
+    @abstractmethod
+    async def route(self, feedback: FeedbackEvent) -> Sequence[FeedbackHandler]:
+        """Return the ordered sequence of handlers that should process ``feedback``."""
+
+
+__all__ = ["FeedbackRouter"]