python-corekit 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

corekit/llm/wire.py

@@ -0,0 +1,199 @@
+"""
+Structured OpenAI completion-chunk parsing and tool-call accumulation.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from corekit.llm.enum import WireField
+from corekit.llm.events import UsageEvent
+from corekit.llm.tools.base import ToolCall
+from corekit.utils import safe_dict, safe_string
+from corekit.utils.collections import attr_or_key
+
+__all__ = [
+    "ChoiceDelta",
+    "CompletionTurn",
+    "FunctionCallDelta",
+    "ToolCallAccumulator",
+    "ToolCallDelta",
+    "UsageInfo",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionCallDelta(BaseModel):
+    """
+    Incremental ``function`` fields on a streamed tool-call delta.
+    """
+
+    name: str = ""
+    arguments: str = ""
+
+
+class ToolCallDelta(BaseModel):
+    """
+    One streamed tool-call fragment (may arrive across many chunks).
+    """
+
+    index: int = 0
+    id: str = ""
+    function: FunctionCallDelta = Field(default_factory=FunctionCallDelta)
+
+    @classmethod
+    def from_raw(cls, raw: Any) -> ToolCallDelta | None:
+        """
+        Parse a dict or SDK object into a delta; return None if index is missing.
+        """
+        index = attr_or_key(raw, WireField.INDEX)
+        if index is None:
+            return None
+        function_raw = safe_dict(attr_or_key(raw, WireField.FUNCTION))
+        return cls(
+            index=int(index),
+            id=safe_string(attr_or_key(raw, WireField.ID)),
+            function=FunctionCallDelta(
+                name=safe_string(attr_or_key(function_raw, WireField.NAME)),
+                arguments=safe_string(attr_or_key(function_raw, WireField.ARGUMENTS)),
+            ),
+        )
+
+
+class ToolCallAccumulator(BaseModel):
+    """
+    Merges streamed tool-call deltas for a single index into one call.
+    """
+
+    id: str = ""
+    name: str = ""
+    arguments: str = ""
+
+    def merge(self, delta: ToolCallDelta) -> None:
+        """
+        Append name/argument fragments from one delta.
+        """
+        if delta.id:
+            self.id = delta.id
+        if delta.function.name:
+            self.name += delta.function.name
+        if delta.function.arguments:
+            self.arguments += delta.function.arguments
+
+    def to_tool_call(self) -> ToolCall:
+        """
+        Parse accumulated argument JSON into a ``ToolCall``.
+        """
+        parsed: dict[str, Any] = {}
+        try:
+            parsed = json.loads(self.arguments)
+        except json.JSONDecodeError:
+            logger.warning("Bad tool args for %r: %r", self.name, self.arguments)
+        return ToolCall(id=self.id, name=self.name, arguments=safe_dict(parsed))
+
+
+class ChoiceDelta(BaseModel):
+    """
+    ``choices[0].delta`` fields we care about from one chunk.
+    """
+
+    content: str | None = None
+    reasoning_content: str | None = None
+    tool_calls: list[ToolCallDelta] = Field(default_factory=list)
+    finish_reason: str | None = None
+
+    @classmethod
+    def from_chunk(cls, chunk: Any) -> ChoiceDelta | None:
+        """
+        Extract the first choice's delta (and finish_reason) from a chunk.
+        """
+        choices = attr_or_key(chunk, WireField.CHOICES)
+        if not choices:
+            return None
+        choice = choices[0]
+        delta_raw = attr_or_key(choice, WireField.DELTA)
+        if delta_raw is None:
+            return cls(finish_reason=attr_or_key(choice, WireField.FINISH_REASON))
+
+        tool_calls: list[ToolCallDelta] = []
+        for raw_tc in attr_or_key(delta_raw, WireField.TOOL_CALLS) or []:
+            parsed = ToolCallDelta.from_raw(raw_tc)
+            if parsed is not None:
+                tool_calls.append(parsed)
+
+        return cls(
+            content=attr_or_key(delta_raw, WireField.CONTENT),
+            reasoning_content=attr_or_key(delta_raw, WireField.REASONING_CONTENT),
+            tool_calls=tool_calls,
+            finish_reason=attr_or_key(choice, WireField.FINISH_REASON),
+        )
+
+
+class UsageInfo(BaseModel):
+    """
+    Token usage from a completion chunk or final response.
+    """
+
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+
+    @classmethod
+    def from_chunk(cls, chunk: Any) -> UsageInfo | None:
+        """
+        Read ``usage`` from a chunk when present.
+        """
+        usage = attr_or_key(chunk, WireField.USAGE)
+        if usage is None:
+            return None
+        return cls(
+            prompt_tokens=attr_or_key(usage, WireField.PROMPT_TOKENS),
+            completion_tokens=attr_or_key(usage, WireField.COMPLETION_TOKENS),
+            total_tokens=attr_or_key(usage, WireField.TOTAL_TOKENS),
+        )
+
+    def to_event(self) -> UsageEvent:
+        """
+        Convert to a stream ``UsageEvent``.
+        """
+        return UsageEvent(
+            total_tokens=self.total_tokens,
+            prompt_tokens=self.prompt_tokens,
+            completion_tokens=self.completion_tokens,
+        )
+
+
+class CompletionTurn(BaseModel):
+    """
+    Mutable state accumulated while streaming one ``complete()`` call.
+    """
+
+    tool_calls: dict[int, ToolCallAccumulator] = Field(default_factory=dict)
+    usage: UsageInfo | None = None
+    finish_reason: str | None = None
+    first_token_ms: float | None = None
+
+    def absorb_delta(self, delta: ChoiceDelta) -> None:
+        """
+        Merge one choice delta into this turn.
+        """
+        if delta.finish_reason:
+            self.finish_reason = delta.finish_reason
+        for tool_delta in delta.tool_calls:
+            bucket = self.tool_calls.setdefault(tool_delta.index, ToolCallAccumulator())
+            bucket.merge(tool_delta)
+
+    def absorb_usage(self, usage: UsageInfo | None) -> None:
+        if usage is not None:
+            self.usage = usage
+
+    def parsed_tool_calls(self) -> list[ToolCall]:
+        """
+        Finalize accumulated tool-call indices into ``ToolCall`` values.
+        """
+        return [self.tool_calls[idx].to_tool_call() for idx in sorted(self.tool_calls)]

corekit/log_monitor/models.py

@@ -75,10 +75,16 @@ class PauseContainerAction(BaseAction):
 
 
 class ExecuteCommandAction(BaseAction):
-    """Execute a shell command"""
+    """
+    Run a command as an argument list.
+
+    ``command`` is split like a shell command line, then ``{container}`` is
+    filled in. It is not passed to a shell, so pipes and redirects are not
+    available.
+    """
 
     type: Literal[ActionType.EXECUTE_COMMAND] = ActionType.EXECUTE_COMMAND
-    command: str = Field(..., description="Command template with {container} placeholder")
+    command: str = Field(..., description="Argument list template with a {container} placeholder")
 
 
 # Union type for all actions

corekit/log_monitor/service.py

@@ -11,6 +11,7 @@ per container so a crash loop cannot become a restart loop.
 """
 
 import re
+import shlex
 import signal
 import subprocess
 import threading
@@ -51,7 +52,7 @@ class LogMonitor(Watchdog):
         config_path: str | None = None,
         config: LogMonitorConfig | None = None,
         notification_service: BaseNotificationService | None = None,
-        enforce_label: bool = False,
+        enforce_label: bool = True,
         max_workers: int | None = None,
         docker_host: str | None = None,
         handle_signals: bool = False,
@@ -61,6 +62,7 @@ class LogMonitor(Watchdog):
         :param config: an already-built configuration, instead of a path.
         :param notification_service: where notifications go; logs by default.
         :param enforce_label: only act on containers carrying the managed label.
+            On by default, matching Watchdog.
         :param handle_signals: install SIGTERM and SIGINT handlers. Off by
             default because installing them is process-global and only the
             program's entry point should decide that; ``run()`` turns it on.
@@ -117,12 +119,31 @@ class LogMonitor(Watchdog):
         }
         return mapping.get(severity, NotificationType.INFO)
 
-    def _send_notification(self, message: str, severity: Severity) -> None:
-        """Send notification using the notification service"""
+    def _send_notification(
+        self,
+        message: str,
+        severity: Severity,
+        container_name: str,
+        throttle: float = 0,
+    ) -> bool:
+        """
+        Send one notification for a container, honoring its throttle.
+
+        This is the only delivery path. A YAML notify action and a rule's
+        ``send_notification`` flag both come through here, so the throttle
+        cannot be recorded in one place and ignored in another.
+        """
+        last_notify = self.last_notify_times.get(container_name, 0.0)
+        if throttle and time.time() - last_notify < throttle:
+            self.debug(f"Notification throttled for {container_name}")
+            return False
+
+        self.last_notify_times[container_name] = time.time()
         notification = Notification(
             message=message, type=self._severity_to_notification_type(severity), meta={"source": "LogMonitor"}
         )
         self._notification_service.notify(notification)
+        return True
 
     def check_rate_limit(self, action_type: ActionType) -> bool:
         """Check if action is within rate limits"""
@@ -145,14 +166,17 @@ class LogMonitor(Watchdog):
         message = action.message.format(container=container_name, text=matched_text)
         self.info(f"[LogAction] {message}")
 
-    def _execute_notify_action(self, action: NotifyAction, container_name: str) -> None:
-        """Execute notify action - check throttle only (actual notification sent separately)"""
-        # Check throttle
-        last_notify = self.last_notify_times.get(container_name, 0.0)
-        if time.time() - last_notify < action.throttle:
-            self.debug(f"Notification throttled for {container_name}")
-            return
-        self.last_notify_times[container_name] = time.time()
+    def _execute_notify_action(
+        self,
+        action: NotifyAction,
+        container_name: str,
+        matched_text: str,
+        severity: Severity,
+        rule_name: str,
+    ) -> None:
+        """Deliver a notification, applying this action's throttle."""
+        message = f"*{rule_name}* in `{container_name}`\n```{matched_text.strip()}```"
+        self._send_notification(message, severity, container_name, throttle=action.throttle)
 
     def _execute_restart_action(self, action: RestartContainerAction, container_name: str) -> None:
         """Execute restart action - delegate to Watchdog parent"""
@@ -172,42 +196,51 @@ class LogMonitor(Watchdog):
             self.info(f"Waiting {action.delay}s before restarting {container_name}")
             time.sleep(action.delay)
 
-        try:
-            # Delegate to parent Watchdog method
-            container = self._client.containers.get(container_name)
-            container.restart()
+        if self.restart_container_by_name(container_name):
             self.restart_counts[container_name].append(time.time())
-            self.info(f"Restarted container: {container_name}")
-        except NotFound:
-            self.error(f"Container '{container_name}' not found")
-        except APIError as e:
-            self.error(f"Failed to restart {container_name}: {e}")
 
     def _execute_pause_action(self, action: PauseContainerAction, container_name: str) -> None:
         """Execute pause action - delegate to Watchdog parent"""
         self.pause_container_by_name(container_name)
 
     def _execute_command_action(self, action: ExecuteCommandAction, container_name: str) -> None:
-        """Execute shell command action"""
-        command = action.command.format(container=container_name)
+        """
+        Run a command as an argument list. The config string is not a shell.
+        """
+        try:
+            argv = [part.format(container=container_name) for part in shlex.split(action.command)]
+        except ValueError as exc:
+            self.error(f"Invalid command for {container_name}: {exc}")
+            return
+        if not argv:
+            self.error(f"Empty command for {container_name}")
+            return
         try:
             result = subprocess.run(
-                command,
-                shell=True,
+                argv,
+                shell=False,
                 capture_output=True,
                 text=True,
-                timeout=30,  # 30 second timeout for safety
+                timeout=30,
             )
+            rendered = " ".join(argv)
             if result.returncode == 0:
-                self.info(f"Executed: {command}\nOutput: {result.stdout}")
+                self.info(f"Executed: {rendered}\nOutput: {result.stdout}")
             else:
-                self.error(f"Command failed: {command}\nError: {result.stderr}")
+                self.error(f"Command failed: {rendered}\nError: {result.stderr}")
         except subprocess.TimeoutExpired:
-            self.error(f"Command timed out: {command}")
+            self.error(f"Command timed out: {action.command}")
         except Exception as e:
             self.error(f"Failed to execute command: {e}")
 
-    def execute_action(self, action: Action, container_name: str, matched_text: str = "") -> None:
+    def execute_action(
+        self,
+        action: Action,
+        container_name: str,
+        matched_text: str = "",
+        severity: Severity = Severity.INFO,
+        rule_name: str = "",
+    ) -> None:
         """Execute configured actions by delegating to specific action handlers"""
         action_type = action.type
 
@@ -221,7 +254,7 @@ class LogMonitor(Watchdog):
         if action_type is ActionType.LOG:
             self._execute_log_action(action, container_name, matched_text)
         elif action_type is ActionType.NOTIFY:
-            self._execute_notify_action(action, container_name)
+            self._execute_notify_action(action, container_name, matched_text, severity, rule_name)
         elif action_type is ActionType.RESTART_CONTAINER:
             self._execute_restart_action(action, container_name)
         elif action_type is ActionType.PAUSE_CONTAINER:
@@ -246,14 +279,20 @@ class LogMonitor(Watchdog):
                 else:
                     self.info(log_message)
 
-                # Execute actions
-                for action in rule.actions:
-                    self.execute_action(action, container_name, line)
-
-                # Send notification if configured
-                if rule.send_notification:
-                    message = f"*{rule.name}* in `{container_name}`\n```{line.strip()}```"
-                    self._send_notification(message, rule.severity)
+                # A notify flag is the same delivery path as a notify action.
+                # Do not send beside it: that path used to ignore the throttle.
+                actions = list(rule.actions)
+                if rule.send_notification and not any(action.type is ActionType.NOTIFY for action in actions):
+                    actions.append(NotifyAction())
+
+                for action in actions:
+                    self.execute_action(
+                        action,
+                        container_name,
+                        line,
+                        severity=rule.severity,
+                        rule_name=rule.name,
+                    )
 
     # FIXME: does this actually make more sense being part of watchdog?
     def monitor_container(self, container_name: str, rules: list[Rule]) -> None:

corekit/notifications/base.py

@@ -8,13 +8,15 @@ Subclass ``BaseNotificationService`` and implement ``_send``::
         Sends notifications by email.
         '''
 
-        def _send(self, message: str) -> None:
-            smtp.send(message)
+        def _send(self, notification: Notification) -> None:
+            smtp.send(notification.message, extra=notification.meta)
 
     service.notify(Notification(message="disk full", type=NotificationType.ERROR))
 
-Override ``_send``, not ``send``: ``notify`` formats the message and calls
-``_send``, so an override with any other name silently does nothing.
+Override ``_send``, not ``notify``, if you only want to replace the transport.
+``notify`` hands the whole ``Notification`` to ``_send``, including ``meta``.
+Events are a different job: they fan a payload out over Redis, they do not
+alert a person.
 """
 
 from corekit.notifications.models import Notification
@@ -36,16 +38,22 @@ class BaseNotificationService(Loggable):
         """
         Render a notification as the text a transport will send.
         """
-        return f"[{notification.type} Notification]: {notification.message}"
+        text = f"[{notification.type} Notification]: {notification.message}"
+        if notification.meta:
+            return f"{text} {notification.meta}"
+        return text
 
-    def _send(self, message: str) -> None:
+    def _send(self, notification: Notification) -> None:
         """
-        Deliver formatted text. Override this in a subclass.
+        Deliver a notification. Override this in a subclass.
+
+        The argument is the notification, not a preformatted string, so a
+        transport can use ``message``, ``type``, and ``meta``.
         """
-        self.warning(message)
+        self.warning(self._format(notification))
 
     def notify(self, notification: Notification) -> None:
         """
-        Format a notification and deliver it.
+        Hand a notification to the transport, including its meta.
         """
-        self._send(self._format(notification))
+        self._send(notification)

corekit/observability/__init__.py

@@ -8,16 +8,23 @@ are the same concern -- knowing what a running system is doing.
 
     class Importer(Benchmarkable):
         def run(self) -> None:
-            self.timing()
-            self.info("starting")
+            self.reset_timing()
+            self.timing("started")
             ...
-            self.timing("finished")
+            self.timing("finished")  # total since reset; latest since started
 """
 
 from corekit.observability.benchmarkable import Benchmarkable
 from corekit.observability.loggable import Loggable
-from corekit.observability.request_context import BaseRequestContext
+from corekit.observability.request_context import BaseRequestContext, RequestContextFilter
 from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
-__all__ = ["BaseRequestContext", "Benchmarkable", "Loggable", "Split", "Timer"]
+__all__ = [
+    "BaseRequestContext",
+    "Benchmarkable",
+    "Loggable",
+    "RequestContextFilter",
+    "Split",
+    "Timer",
+]

corekit/observability/benchmarkable.py

@@ -1,12 +1,44 @@
+from typing import Any
+
 from corekit.observability.loggable import Loggable
+from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
 
 class Benchmarkable(Loggable):
-    def __init__(self) -> None:
-        super().__init__()
+    """
+    ``Loggable`` plus split timing.
+
+    ``__init__`` forwards ``*args``/``**kwargs`` the same way ``Loggable``
+    does, so a service can sit in a cooperative ``super()`` chain without
+    this class swallowing the arguments the next base expects.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
         self._timing = Timer()
 
-    def timing(self, split_name: str | None = None) -> None:
-        split_message = str(self._timing.split(split_name=split_name))
-        self.info(split_message)
+    def reset_timing(self) -> None:
+        """
+        Restart the underlying timer for a new unit of work.
+        """
+        self._timing.reset()
+
+    def elapsed_ms(self) -> float:
+        """
+        Milliseconds since start (or last ``reset_timing``), without a split.
+        """
+        return self._timing.elapsed() * 1000
+
+    def timing(self, split_name: str | None = None) -> Split:
+        """
+        Log the time since the last split and return it.
+
+        ``Split.total`` / ``Split.total_ms`` are since start (or last reset).
+        ``Split.latest`` / ``Split.latest_ms`` are since the previous split.
+        The log line is unchanged. The return value is for a caller that wants
+        the numbers without parsing that line.
+        """
+        split = self._timing.split(split_name=split_name)
+        self.info(str(split))
+        return split

corekit/observability/loggable.py

@@ -1,6 +1,8 @@
 import logging
 from typing import Any
 
+from corekit.observability.request_context import RequestContextFilter
+
 
 class Loggable:
     """
@@ -8,10 +10,16 @@ class Loggable:
 
     Accepts and ignores ``*args``/``**kwargs`` so it can sit anywhere in a
     cooperative ``super().__init__()`` chain.
+
+    The logger name is the class name, not ``module.Class``. Consuming
+    projects filter on that name; renaming it is a log-config change, not a
+    local cleanup. Request context is attached as record attributes instead,
+    so a formatter can include it without renaming the logger.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.logger = logging.getLogger(self.__class__.__name__)
+        _attach_request_context(self.logger)
 
     def debug(self, message: str, **kwargs: Any) -> None:
         self.logger.debug(message, **kwargs)
@@ -27,3 +35,16 @@ class Loggable:
 
     def exception(self, message: str, **kwargs: Any) -> None:
         self.logger.exception(message, **kwargs)
+
+
+def _attach_request_context(logger: logging.Logger) -> None:
+    """
+    Attach the request-context filter once per logger name.
+
+    Loggers are process-global and keyed by name, so every instance of a
+    class shares one. Adding the filter again would stamp the same fields
+    twice.
+    """
+    if any(isinstance(existing, RequestContextFilter) for existing in logger.filters):
+        return
+    logger.addFilter(RequestContextFilter())

corekit/observability/request_context.py

@@ -27,13 +27,14 @@ Each subclass gets its own storage, so one application's context cannot be read
 through another's class.
 """
 
+import logging
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
-from typing import Any, Iterator, Self
+from typing import Any, ClassVar, Iterator, Self
 
 from pydantic import BaseModel
 
-__all__ = ["BaseRequestContext"]
+__all__ = ["BaseRequestContext", "RequestContextFilter"]
 
 
 class BaseRequestContext(BaseModel):
@@ -45,12 +46,18 @@ class BaseRequestContext(BaseModel):
     between them leaks the context into whatever runs next on that task.
     """
 
+    #: Subclasses that own storage. The logging filter walks this rather than
+    #: guessing which application's context class is in use.
+    _known_subclasses: ClassVar[list[type["BaseRequestContext"]]] = []
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
         Give every subclass its own ContextVar.
         """
         super().__init_subclass__(**kwargs)
         cls._context_var = ContextVar(f"{cls.__module__}.{cls.__name__}", default=None)
+        if cls not in BaseRequestContext._known_subclasses:
+            BaseRequestContext._known_subclasses.append(cls)
 
     @classmethod
     def _var(cls) -> ContextVar[Any]:
@@ -133,3 +140,49 @@ class BaseRequestContext(BaseModel):
             yield type(self).current()
         finally:
             type(self).deactivate(token)
+
+
+class RequestContextFilter(logging.Filter):
+    """
+    Stamp the active request context onto each log record.
+
+    The message is left alone, so existing log lines and anything that
+    matches them stay stable. Fields land on the record for a formatter
+    that opts in: ``%(request_context)s`` is a compact summary, and
+    ``request_context_fields`` is the dumped model. Both are always set,
+    to an empty string and an empty dict when nothing is active, so a
+    format string that names them does not raise.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        fields: dict[str, Any] = {}
+        parts: list[str] = []
+        for cls in BaseRequestContext._known_subclasses:
+            current = cls.current()
+            if current is None:
+                continue
+            dumped = _dump_context(current)
+            if not dumped:
+                continue
+            fields[cls.__name__] = dumped
+            rendered = ", ".join(f"{key}={value}" for key, value in dumped.items())
+            parts.append(f"{cls.__name__}({rendered})")
+
+        record.request_context = " ".join(parts)
+        record.request_context_fields = fields
+        return True
+
+
+def _dump_context(context: BaseRequestContext) -> dict[str, Any]:
+    """
+    JSON-safe fields, or stringified values if a field will not dump.
+    """
+    try:
+        dumped = context.model_dump(mode="json")
+    except Exception:
+        dumped = {key: getattr(context, key, None) for key in type(context).model_fields}
+    return {key: value if _is_log_safe(value) else str(value) for key, value in dumped.items()}
+
+
+def _is_log_safe(value: Any) -> bool:
+    return value is None or isinstance(value, (str, int, float, bool))