python-corekit 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

corekit/http/stream.py

@@ -0,0 +1,110 @@
+"""
+Decode streaming HTTP response bodies into typed events.
+
+``BaseHttpClient.stream_request`` yields a raw ``httpx.Response``. Decoders
+turn that into an async iterator of useful values (SSE text, SSE JSON, …).
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from corekit.observability import Loggable
+
+__all__ = [
+    "SseDecoder",
+    "SseJsonDecoder",
+    "SseTextDecoder",
+    "StreamDecoder",
+]
+
+T = TypeVar("T")
+
+
+class StreamDecoder(Loggable, ABC, Generic[T]):
+    """
+    Turn a streaming ``httpx.Response`` into an async iterator of ``T``.
+    """
+
+    @abstractmethod
+    def decode(self, response: httpx.Response) -> AsyncIterator[T]:
+        """
+        Consume ``response`` and yield decoded items.
+
+        Implemented as an async generator on concrete subclasses.
+        """
+        ...
+
+
+class SseDecoder(StreamDecoder[T], ABC):
+    """
+    Server-Sent Events framing: ``data:`` lines, skip comments / blanks.
+
+    Optional ``done_sentinel`` (e.g. OpenAI's ``[DONE]``) ends the stream
+    early. Subclasses interpret each data payload via ``_decode_payload``.
+    """
+
+    def __init__(self, *, done_sentinel: str | None = None) -> None:
+        super().__init__()
+        self.done_sentinel = done_sentinel
+
+    async def decode(self, response: httpx.Response) -> AsyncIterator[T]:
+        async for data in self._iter_data_payloads(response):
+            item = self._decode_payload(data)
+            if item is not None:
+                yield item
+
+    async def _iter_data_payloads(self, response: httpx.Response) -> AsyncIterator[str]:
+        async for line in response.aiter_lines():
+            line = line.strip()
+            if not line.startswith("data:"):
+                continue
+            data = line.removeprefix("data:").strip()
+            if not data:
+                continue
+            if self.done_sentinel is not None and data == self.done_sentinel:
+                return
+            yield data
+
+    @abstractmethod
+    def _decode_payload(self, data: str) -> T | None:
+        """
+        Map one SSE data payload to ``T``, or ``None`` to skip.
+        """
+
+
+class SseTextDecoder(SseDecoder[str]):
+    """
+    Yield SSE data payloads as plain strings.
+    """
+
+    def _decode_payload(self, data: str) -> str | None:
+        return data
+
+
+class SseJsonDecoder(SseDecoder[dict[str, Any]]):
+    """
+    Yield SSE data payloads parsed as JSON objects.
+
+    Non-object JSON and decode failures are skipped (with a warning). Default
+    ``done_sentinel`` matches OpenAI-compatible chat streams.
+    """
+
+    def __init__(self, *, done_sentinel: str | None = "[DONE]") -> None:
+        super().__init__(done_sentinel=done_sentinel)
+
+    def _decode_payload(self, data: str) -> dict[str, Any] | None:
+        try:
+            payload = json.loads(data)
+        except json.JSONDecodeError:
+            self.warning(f"[SseJsonDecoder] Skipping bad SSE payload: {data!r}")
+            return None
+        if isinstance(payload, dict):
+            return payload
+        self.warning(f"[SseJsonDecoder] Skipping non-object SSE JSON: {type(payload).__name__}")
+        return None

corekit/jobs/runner.py

@@ -18,6 +18,7 @@ import inspect
 import logging
 from typing import Any
 
+from corekit.exceptionator.jobs import get_run_task_hook
 from corekit.jobs.registry import task_registry
 from corekit.utils.payload import decode_payload
 
@@ -34,8 +35,10 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
     raises, and the original exception is re-raised so the queue records the
     job as failed. A hook that raises does not mask the original error.
     ``last_result`` and ``last_error`` are set on the task before the hook
-    runs. A coroutine ``task_function`` is awaited. ``timeout`` is not applied
-    here; the scheduling adapter owns that.
+    runs. When an Exceptionator ``run_task`` hook is installed it runs after
+    ``last_error`` is set and before ``failure()``. A coroutine
+    ``task_function`` is awaited. ``timeout`` is not applied here; the
+    scheduling adapter owns that.
 
     Args:
         task_name: The registered name of the task to run.
@@ -58,6 +61,7 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
     except Exception as exc:
         task.last_result = None
         task.last_error = exc
+        _run_exceptionator_hook(task_name, exc)
         _run_hook(task, "failure", args, kwargs)
         raise
 
@@ -67,6 +71,22 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
     return result
 
 
+def _run_exceptionator_hook(task_name: str, exc: BaseException) -> None:
+    """
+    Run the optional Exceptionator hook without replacing the original error.
+    """
+    hook = get_run_task_hook()
+    if hook is None:
+        return
+    try:
+        hook(task_name, exc)
+    except Exception:
+        logger.exception(
+            "Exceptionator run_task hook raised for %s; the task's own outcome stands",
+            task_name,
+        )
+
+
 def _run_hook(task: Any, hook_name: str, args: list[Any], kwargs: dict[str, Any]) -> None:
     """
     Run a success or failure hook without letting it replace the real outcome.

corekit/llm/__init__.py

@@ -0,0 +1,134 @@
+"""
+OpenAI-shaped chat primitives, tool registry, and agentic loop.
+
+Wire format in, structured stream events out. Use ``ChatCompletionsClient``
+against any OpenAI-compatible server (llama.cpp, vLLM, OpenAI, …):
+
+    from corekit.llm import ChatCompletionsClient, PromptLoader, ToolLoop, ToolRegistry
+
+    client = ChatCompletionsClient("http://localhost:8080/v1", model="local")
+    prompts = PromptLoader("/path/to/prompts")
+    tmpl = prompts.load("summarization", "general", system="1.0.0", user="1.0.0")
+    registry = ToolRegistry()
+    registry.register(MyTool())
+    loop = ToolLoop(client, registry)
+    async for event in loop.stream(tmpl.messages(text="…", style="brief", length="1 paragraph")):
+        ...
+"""
+
+from corekit.llm.client import DEFAULT_LLM_TIMEOUT, ChatCompletionsClient
+from corekit.llm.enum import (
+    ContentPartType,
+    FinishReason,
+    Role,
+    StopReason,
+    StreamEventType,
+    ToolCallType,
+    ToolKind,
+    WireField,
+)
+from corekit.llm.events import (
+    DoneEvent,
+    StopEvent,
+    StreamEvent,
+    TextEvent,
+    ThinkingEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+    UIComponentEvent,
+    UsageEvent,
+)
+from corekit.llm.messages import (
+    AssistantMessage,
+    ChatTurn,
+    Message,
+    SystemMessage,
+    ToolMessage,
+    UserMessage,
+)
+from corekit.llm.prompts import (
+    DEFAULT_PROMPT_VERSION,
+    PromptError,
+    PromptFileRole,
+    PromptKind,
+    PromptLoader,
+    PromptNotFoundError,
+    PromptTemplate,
+    ThinkingLevel,
+)
+from corekit.llm.protocols import ChatClient, MetricsRecorder
+from corekit.llm.streaming import (
+    THINK_PATTERN,
+    ModelStreamingState,
+    ThinkingMarker,
+    ThinkingMarkerPair,
+    strip_thinking,
+)
+from corekit.llm.tools.base import Tool, ToolCall, ToolResult
+from corekit.llm.tools.detection import MAX_TOOL_ITERATIONS, ToolCallLoopDetector
+from corekit.llm.tools.loop import ToolLoop
+from corekit.llm.tools.registry import ToolRegistry
+from corekit.llm.wire import (
+    ChoiceDelta,
+    CompletionTurn,
+    FunctionCallDelta,
+    ToolCallAccumulator,
+    ToolCallDelta,
+    UsageInfo,
+)
+
+__all__ = [
+    "DEFAULT_LLM_TIMEOUT",
+    "DEFAULT_PROMPT_VERSION",
+    "MAX_TOOL_ITERATIONS",
+    "THINK_PATTERN",
+    "AssistantMessage",
+    "ChatClient",
+    "ChatCompletionsClient",
+    "ChatTurn",
+    "ChoiceDelta",
+    "CompletionTurn",
+    "ContentPartType",
+    "DoneEvent",
+    "FinishReason",
+    "FunctionCallDelta",
+    "Message",
+    "MetricsRecorder",
+    "ModelStreamingState",
+    "PromptError",
+    "PromptFileRole",
+    "PromptKind",
+    "PromptLoader",
+    "PromptNotFoundError",
+    "PromptTemplate",
+    "Role",
+    "StopEvent",
+    "StopReason",
+    "StreamEvent",
+    "StreamEventType",
+    "SystemMessage",
+    "TextEvent",
+    "ThinkingEvent",
+    "ThinkingLevel",
+    "ThinkingMarker",
+    "ThinkingMarkerPair",
+    "Tool",
+    "ToolCall",
+    "ToolCallAccumulator",
+    "ToolCallDelta",
+    "ToolCallEvent",
+    "ToolCallLoopDetector",
+    "ToolCallType",
+    "ToolKind",
+    "ToolLoop",
+    "ToolMessage",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolResultEvent",
+    "UIComponentEvent",
+    "UsageEvent",
+    "UsageInfo",
+    "UserMessage",
+    "WireField",
+    "strip_thinking",
+]

corekit/llm/client.py

@@ -0,0 +1,179 @@
+"""
+OpenAI-compatible chat completions client.
+
+A thin ``BaseApiClient`` for ``/chat/completions``. Transport and status
+handling come from the HTTP layer; streaming bodies go through
+``SseJsonDecoder``. This module only knows the OpenAI request wire shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Coroutine, Mapping, Sequence
+from http import HTTPMethod
+from typing import Any, Literal, overload
+
+from corekit.concurrency.decorators import allow_sync
+from corekit.http import BaseApiClient, BaseApiResponse, SseJsonDecoder
+from corekit.llm.messages import ChatTurn, Message
+
+__all__ = ["ChatCompletionsClient", "DEFAULT_LLM_TIMEOUT"]
+
+# LLM calls can run for minutes; the HTTP default of 30s is too short.
+DEFAULT_LLM_TIMEOUT = 600.0
+
+# Owned by this client — sampling kwargs and friends pass through untouched.
+_BODY_RESERVED = frozenset({"model", "messages", "stream", "stream_options", "tools", "tool_choice"})
+
+
+class ChatCompletionsClient(BaseApiClient):
+    """
+    OpenAI-shaped chat completions over HTTP.
+
+        client = ChatCompletionsClient("http://localhost:8080/v1", model="local")
+
+        # one-shot: a dict from sync code, a coroutine inside a running loop
+        result = client.complete([UserMessage(content="hi")])
+        result = await client.complete([UserMessage(content="hi")])
+
+        # streaming is always an async iterator — there is no sync equivalent
+        async for chunk in client.complete(messages, stream=True):
+            ...
+
+    ``base_url`` should include the API root (typically ``…/v1``). Accepts
+    ``Message`` instances or raw OpenAI message dicts.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        model: str | None = None,
+        timeout: float = DEFAULT_LLM_TIMEOUT,
+        **kwargs: Any,
+    ) -> None:
+        self._api_key = api_key
+        self._model = model
+        # Trailing slash so urljoin keeps the ``/v1`` segment for relative paths.
+        self._api_base = base_url if base_url.endswith("/") else f"{base_url}/"
+        self._stream_decoder = SseJsonDecoder()
+        super().__init__(timeout=timeout, **kwargs)
+
+    @property
+    def base_url(self) -> str:
+        return self._api_base
+
+    @property
+    def headers(self) -> dict[str, str]:
+        if not self._api_key:
+            return {}
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def _resolve_model(self, model: str | None) -> str:
+        resolved = model if model is not None else self._model
+        if not resolved:
+            raise ValueError("model is required (pass model= to complete() or the constructor)")
+        return resolved
+
+    def _build_body(
+        self,
+        messages: Sequence[ChatTurn],
+        *,
+        stream: bool,
+        tools: Sequence[Mapping[str, Any]] | None = None,
+        model: str | None = None,
+        internal: bool = False,
+        **params: Any,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "model": self._resolve_model(model),
+            "messages": Message.as_wire(messages, internal=internal),
+            "stream": stream,
+        }
+        if stream:
+            body["stream_options"] = {"include_usage": True}
+        if tools:
+            body["tools"] = list(tools)
+            body["tool_choice"] = params.pop("tool_choice", "auto")
+        for key, value in params.items():
+            if key not in _BODY_RESERVED:
+                body[key] = value
+        return body
+
+    @overload
+    def complete(
+        self,
+        messages: Sequence[ChatTurn],
+        *,
+        tools: Sequence[Mapping[str, Any]] | None = None,
+        model: str | None = None,
+        stream: Literal[False] = False,
+        internal: bool = False,
+        **kwargs: Any,
+    ) -> dict[str, Any] | Coroutine[Any, Any, dict[str, Any]]: ...
+
+    @overload
+    def complete(
+        self,
+        messages: Sequence[ChatTurn],
+        *,
+        tools: Sequence[Mapping[str, Any]] | None = None,
+        model: str | None = None,
+        stream: Literal[True],
+        internal: bool = False,
+        **kwargs: Any,
+    ) -> AsyncIterator[dict[str, Any]]: ...
+
+    def complete(
+        self,
+        messages: Sequence[ChatTurn],
+        *,
+        tools: Sequence[Mapping[str, Any]] | None = None,
+        model: str | None = None,
+        stream: bool = False,
+        internal: bool = False,
+        **kwargs: Any,
+    ) -> dict[str, Any] | Coroutine[Any, Any, dict[str, Any]] | AsyncIterator[dict[str, Any]]:
+        """
+        POST ``/chat/completions``.
+
+        ``stream=False`` (default) uses ``@allow_sync``: a script gets the
+        response dict back; inside a running event loop you must ``await`` it.
+        ``stream=True`` is always an async iterator — ``@allow_sync`` only
+        unwraps one awaitable, and buffering a stream would defeat streaming.
+        """
+        body = self._build_body(
+            messages,
+            stream=stream,
+            tools=tools,
+            model=model,
+            internal=internal,
+            **kwargs,
+        )
+        if stream:
+            return self._complete_stream(body)
+        return self._complete(body)
+
+    @allow_sync
+    async def _complete(self, body: dict[str, Any]) -> dict[str, Any]:
+        self.info(
+            f"[ChatCompletionsClient] Completing {body['model']!r} — "
+            f"messages={len(body['messages'])}, tools={'tools' in body}"
+        )
+        response = await self.post("chat/completions", json=body)
+        response.raise_for_status()
+        if not response.data:
+            raise ValueError(f"chat/completions returned non-JSON body: {response.text!r}")
+        return dict(response.data)
+
+    async def _complete_stream(self, body: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        self.info(
+            f"[ChatCompletionsClient] Streaming {body['model']!r} — "
+            f"messages={len(body['messages'])}, tools={'tools' in body}"
+        )
+        async with self.stream_request(HTTPMethod.POST, "chat/completions", json=body) as response:
+            if int(response.status_code) >= 400:
+                error_body = (await response.aread()).decode("utf-8", errors="replace")
+                BaseApiResponse(status_code=response.status_code, text=error_body).raise_for_status()
+            async for chunk in self._stream_decoder.decode(response):
+                yield chunk

corekit/llm/enum.py

@@ -0,0 +1,123 @@
+"""
+Wire-facing LLM enumerations.
+"""
+
+from corekit.schemas import StringEnum
+
+__all__ = [
+    "ContentPartType",
+    "FinishReason",
+    "Role",
+    "StopReason",
+    "StreamEventType",
+    "ToolCallType",
+    "ToolKind",
+    "WireField",
+]
+
+
+class Role(StringEnum):
+    """
+    OpenAI-shaped chat roles. Product bookkeeping roles (slash commands, and
+    so on) stay in the consumer.
+    """
+
+    USER = "user"
+    SYSTEM = "system"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+    def is_for_llm(self) -> bool:
+        """
+        True when this role may be included in model context.
+        """
+        return self in {Role.USER, Role.SYSTEM, Role.ASSISTANT, Role.TOOL}
+
+
+class ToolKind(StringEnum):
+    """
+    How a tool participates in the agentic loop.
+    """
+
+    DATA = "data"  # executed server-side; result fed back into the model
+    UI = "ui"  # payload for the client; halts the model loop
+
+
+class StreamEventType(StringEnum):
+    """
+    Kind of event yielded by a tool-aware streaming loop.
+    """
+
+    TEXT = "text"
+    THINKING = "thinking"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    UI_COMPONENT = "ui_component"
+    USAGE = "usage"
+    DONE = "done"
+    STOP = "stop"
+
+
+class StopReason(StringEnum):
+    """
+    Why a ``StopEvent`` ended the loop early.
+    """
+
+    LOOP_DETECTED = "loop_detected"
+    MAX_ITERATIONS = "max_iterations"
+
+
+class FinishReason(StringEnum):
+    """
+    OpenAI-compatible ``finish_reason`` values on a completion choice.
+    """
+
+    STOP = "stop"
+    TOOL_CALLS = "tool_calls"
+    LENGTH = "length"
+    CONTENT_FILTER = "content_filter"
+
+
+class ContentPartType(StringEnum):
+    """
+    Multimodal content-part ``type`` values in OpenAI chat messages.
+    """
+
+    TEXT = "text"
+    IMAGE_URL = "image_url"
+
+
+class ToolCallType(StringEnum):
+    """
+    OpenAI tool-call ``type`` on assistant messages.
+    """
+
+    FUNCTION = "function"
+
+
+class WireField(StringEnum):
+    """
+    Recurring OpenAI wire field names used across messages and chunks.
+    """
+
+    ROLE = "role"
+    CONTENT = "content"
+    TOOL_CALLS = "tool_calls"
+    TOOL_CALL_ID = "tool_call_id"
+    REASONING_CONTENT = "reasoning_content"
+    TYPE = "type"
+    ID = "id"
+    NAME = "name"
+    ARGUMENTS = "arguments"
+    FUNCTION = "function"
+    INDEX = "index"
+    CHOICES = "choices"
+    DELTA = "delta"
+    USAGE = "usage"
+    FINISH_REASON = "finish_reason"
+    PROMPT_TOKENS = "prompt_tokens"
+    COMPLETION_TOKENS = "completion_tokens"
+    TOTAL_TOKENS = "total_tokens"
+    IMAGE_URL = "image_url"
+    URL = "url"
+    TEXT = "text"

corekit/llm/events.py

@@ -0,0 +1,96 @@
+"""
+Transport-agnostic stream events from a tool-aware loop.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from corekit.llm.enum import StopReason, StreamEventType
+from corekit.llm.tools.base import ToolCall, ToolResult
+
+__all__ = [
+    "DoneEvent",
+    "StopEvent",
+    "StreamEvent",
+    "TextEvent",
+    "ThinkingEvent",
+    "ToolCallEvent",
+    "ToolResultEvent",
+    "UIComponentEvent",
+    "UsageEvent",
+]
+
+
+class StreamEvent(BaseModel):
+    """
+    Base event yielded by the tool-aware streaming loop.
+
+    Subclasses fix ``kind``; ``payload()`` is what an SSE ``data:`` line would
+    carry (``kind`` is omitted — it belongs on the event name).
+    """
+
+    kind: StreamEventType
+
+    def payload(self) -> dict[str, Any]:
+        """
+        JSON-serializable payload without the ``kind`` field.
+        """
+        return self.model_dump(exclude={"kind"})
+
+
+class TextEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.TEXT
+    content: str
+
+
+class ThinkingEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.THINKING
+    content: str
+
+
+class ToolCallEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.TOOL_CALL
+    tool_call: ToolCall
+
+    def payload(self) -> dict[str, Any]:
+        return self.tool_call.model_dump()
+
+
+class ToolResultEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.TOOL_RESULT
+    tool_result: ToolResult
+
+    def payload(self) -> dict[str, Any]:
+        return self.tool_result.model_dump()
+
+
+class UIComponentEvent(StreamEvent):
+    """
+    Halt payload for a UI tool — shape is consumer-defined.
+    """
+
+    kind: StreamEventType = StreamEventType.UI_COMPONENT
+    tool_call_id: str
+    name: str
+    component: dict[str, Any]
+
+
+class UsageEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.USAGE
+    total_tokens: int | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+
+
+class StopEvent(StreamEvent):
+    kind: StreamEventType = StreamEventType.STOP
+    reason: StopReason
+
+
+class DoneEvent(StreamEvent):
+    """
+    Normal completion of a streamed turn with no further tool work.
+    """
+
+    kind: StreamEventType = StreamEventType.DONE