local2 0.1.0__py3-none-any.whl

local/__init__.py

@@ -0,0 +1 @@
+"""LoCAL2 package root."""

local/agents/base_agent.py

@@ -0,0 +1,76 @@
+"""BaseAgent — common behaviour for all LoCAL2 system-triggered agents."""
+from __future__ import annotations
+
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from local.protocol.envelope import MessageEnvelope
+from local.protocol.subjects import AGENT_TRANSITION
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """Abstract base for all system-triggered LoCAL2 agents.
+
+    Subclasses must:
+    - declare ``AGENT_ID`` as a class variable
+    - set ``self._pub``, ``self._sub``, and ``self._sm`` in ``__init__``
+    - implement ``_dispatch()`` to route envelopes to their handlers
+
+    ``run()`` provides the standard receive loop. ``GeneratorAgent`` overrides
+    it for startup sequencing; other agents inherit it directly.
+    """
+
+    AGENT_ID: ClassVar[str]
+    _pub: Any
+    _sub: Any
+    _sm: Any
+
+    def run(self) -> None:
+        """Block on the bus and dispatch each envelope; log receive errors."""
+        logger.info("%s ready", self.AGENT_ID)
+        while True:
+            try:
+                envelope = self._sub.receive()
+            except Exception as exc:
+                logger.error("%s: receive error: %s", self.__class__.__name__, exc)
+                continue
+            self._dispatch(envelope)
+
+    @abstractmethod
+    def _dispatch(self, envelope: MessageEnvelope) -> None:
+        """Route an incoming envelope to the appropriate handler."""
+        ...
+
+    def _do_transition(self, action: Any) -> None:
+        """Execute a state machine transition and publish AGENT_TRANSITION.
+
+        Wrapped in try/except — transition logging must never propagate and
+        interrupt the agent's main work. Calls ``_after_transition()`` after
+        a successful transition so subclasses can add side-effects (e.g.
+        ``GeneratorAgent`` uses it to publish a status snapshot).
+        """
+        from_state = self._sm.state
+        to_state = self._sm.transition(action)
+        try:
+            self._pub.publish(MessageEnvelope.create(
+                message_type="agent_transition",
+                subject=AGENT_TRANSITION,
+                sender_id=self.AGENT_ID,
+                payload={
+                    "agent":  self.AGENT_ID,
+                    "from":   from_state.value,
+                    "action": action.value,
+                    "to":     to_state.value,
+                },
+                correlation_id=str(uuid.uuid4()),
+            ))
+        except Exception:
+            pass
+        self._after_transition()
+
+    def _after_transition(self) -> None:
+        """Hook called after every transition. Default: no-op."""

local/agents/critic_actions.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class CriticAction(Enum):
+    RECEIVE = "receive"
+    START_GRADE = "start_grade"
+    PUBLISH = "publish"
+    FAIL = "fail"
+    RESET = "reset"

local/agents/critic_agent.py

@@ -0,0 +1,139 @@
+"""CriticAgent — post-generation quality observer.
+
+Subscribes to response.generation. For each answer, calls Prometheus via
+OllamaBackend to produce an absolute quality score (1–5) and a feedback
+string. Publishes critique.result.
+
+Never blocks or raises: on Prometheus failure or score parse failure,
+publishes critique.result with score=None so downstream consumers
+(MemoryAgent, UI) can treat null as "not graded" and continue normally.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from local.agents.base_agent import BaseAgent
+from local.agents.critic_actions import CriticAction
+from local.agents.critic_states import CriticState
+from local.agents.critic_transitions import CriticStateMachine
+from local.config_loader import get_config
+from local.protocol.envelope import MessageEnvelope
+from local.protocol.subjects import CRITIQUE, RESPONSE_GENERATION
+from local.services.ollama_backend import OllamaBackend
+from local.transport.bus_config import make_participant_bus
+
+logger = logging.getLogger(__name__)
+
+
+class CriticAgent(BaseAgent):
+    """Post-generation quality observer.
+
+    Grades every non-tool-call answer with an absolute score (1–5) via
+    Prometheus. Never raises — publishes ``score=None`` on any Prometheus
+    failure so downstream consumers (MemoryAgent, UI) can treat null as
+    "not graded" and continue normally.
+    """
+
+    AGENT_ID = "critic"
+
+    def __init__(self, llm: OllamaBackend | None = None) -> None:
+        """Initialize the CriticAgent.
+
+        Config keys read from ``config/critic.yaml``: ``model``, ``rubric``,
+        ``grade_prompt``, ``pairwise_prompt``, ``pairwise_buffer_max``,
+        ``num_ctx``, ``temperature``, ``grade_timeout``.
+
+        Args:
+            llm: Injected for testing; defaults to an ``OllamaBackend`` built
+                from config.
+        """
+        cfg = get_config("critic")
+        model: str = cfg.get("model", "prometheus:7b")
+        self._rubric: str = cfg.get("rubric", "")
+        self._grade_prompt: str = cfg.get("grade_prompt", "").strip()
+        self._options: dict = {
+            "num_ctx": cfg.get("num_ctx", 4096),
+            "temperature": cfg.get("temperature", 0.0),
+        }
+        timeout: int = cfg.get("grade_timeout", 30)
+        self._llm = llm or OllamaBackend(model=model, agent_name=self.AGENT_ID, timeout=timeout)
+        self._pub, self._sub = make_participant_bus([RESPONSE_GENERATION])
+        self._sm = CriticStateMachine()
+
+    def _dispatch(self, envelope: MessageEnvelope) -> None:
+        if envelope.subject == RESPONSE_GENERATION:
+            try:
+                self._handle_generation(envelope)
+            except Exception as exc:
+                logger.error("CriticAgent: unhandled error: %s", exc, exc_info=True)
+                if self._sm.state != CriticState.IDLE:
+                    self._do_transition(CriticAction.FAIL)
+                    self._do_transition(CriticAction.RESET)
+
+    def _handle_generation(self, envelope: MessageEnvelope) -> None:
+        payload = envelope.payload
+        query: str = payload.get("query", "").strip()
+        answer: str = payload.get("answer", "").strip()
+        session_id: str = payload.get("session_id") or ""
+        query_id: str = payload.get("query_id") or ""
+        correlation_id: str = envelope.correlation_id or query_id
+
+        if not query or not answer or payload.get("error"):
+            return
+
+        if payload.get("tool_calls"):
+            logger.debug("CriticAgent: skipping grade — tool calls present")
+            return
+
+        # -- Absolute grade --------------------------------------------------
+        self._do_transition(CriticAction.RECEIVE)
+        self._do_transition(CriticAction.START_GRADE)
+
+        score, feedback = self._grade(query, answer)
+
+        if score is None:
+            self._do_transition(CriticAction.FAIL)
+        else:
+            self._do_transition(CriticAction.PUBLISH)
+
+        self._pub.publish(MessageEnvelope.create(
+            message_type="critique",
+            subject=CRITIQUE,
+            sender_id=self.AGENT_ID,
+            payload={
+                "score": score,
+                "feedback": feedback,
+                "query": query,
+                "answer": answer,
+                "session_id": session_id,
+                "query_id": query_id,
+            },
+            correlation_id=correlation_id,
+            metadata={"session_id": session_id},
+        ))
+
+        self._do_transition(CriticAction.RESET)
+
+    def _grade(self, query: str, answer: str) -> tuple[int | None, str]:
+        """Call Prometheus absolute grading. Returns (score_or_None, feedback_text)."""
+        prompt = self._grade_prompt.format(query=query, answer=answer, rubric=self._rubric)
+        text, _ = self._llm.chat(
+            [{"role": "user", "content": prompt}],
+            options=self._options,
+        )
+        if not text:
+            logger.warning("CriticAgent: Prometheus returned empty response")
+            return None, ""
+
+        m = re.search(r'\[RESULT\]\s*([1-5])', text)
+        score = int(m.group(1)) if m else None
+        if score is None:
+            logger.warning("CriticAgent: could not parse score from: %r", text[:120])
+
+        feedback = re.sub(r'\s*\[RESULT\].*$', '', text, flags=re.DOTALL).strip()
+        if feedback.lower().startswith("feedback:"):
+            feedback = feedback[len("feedback:"):].strip()
+
+        return score, feedback
+
+

local/agents/critic_states.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class CriticState(Enum):
+    IDLE = "idle"
+    RECEIVING = "receiving"
+    GRADING = "grading"
+    PUBLISHING = "publishing"
+    ERROR = "error"

local/agents/critic_transitions.py

@@ -0,0 +1,33 @@
+"""CriticAgent transition table and StateMachine executor."""
+from local.agents.critic_actions import CriticAction
+from local.agents.critic_states import CriticState
+
+TRANSITIONS: dict[tuple[CriticState, CriticAction], CriticState] = {
+    (CriticState.IDLE,            CriticAction.RECEIVE):        CriticState.RECEIVING,
+    (CriticState.RECEIVING,       CriticAction.START_GRADE):    CriticState.GRADING,
+    (CriticState.GRADING,         CriticAction.PUBLISH):        CriticState.PUBLISHING,
+    (CriticState.GRADING,         CriticAction.FAIL):           CriticState.ERROR,
+    (CriticState.PUBLISHING,      CriticAction.RESET):          CriticState.IDLE,
+    (CriticState.ERROR,           CriticAction.RESET):          CriticState.IDLE,
+}
+
+
+class CriticStateMachine:
+    """Enforces the critic transition table. Raises on illegal transitions."""
+
+    def __init__(self) -> None:
+        self._state = CriticState.IDLE
+
+    @property
+    def state(self) -> CriticState:
+        return self._state
+
+    def transition(self, action: CriticAction) -> CriticState:
+        key = (self._state, action)
+        next_state = TRANSITIONS.get(key)
+        if next_state is None:
+            raise ValueError(
+                f"Illegal transition: state={self._state.value!r} action={action.value!r}"
+            )
+        self._state = next_state
+        return self._state

local/agents/generator_actions.py

@@ -0,0 +1,15 @@
+"""GeneratorAgent action definitions."""
+
+from enum import Enum
+
+
+class GeneratorAction(Enum):
+    RECEIVE = "receive"                 # query.received consumed
+    START_GENERATION = "start_generation"   # begin ollama.chat()
+    DISPATCH_TOOL = "dispatch_tool"     # tool_calls present, publishing tool.request.*
+    AWAIT_RESULT = "await_result"       # tool.request.* published, blocking on tool.result.*
+    TOOL_RESULT = "tool_result"         # tool.result.* received, resume loop
+    TOOL_TIMEOUT = "tool_timeout"       # no tool.result.* within deadline, inject error
+    PUBLISH = "publish"                 # no tool calls, answer ready
+    RESET = "reset"                     # response.generation published, back to idle
+    FAIL = "fail"                       # unrecoverable error