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

corekit/jobs/runner.py

@@ -13,6 +13,8 @@ Enqueueing a bound method makes the queue serialize the instance, which is the
 thing worth avoiding.
 """
 
+import asyncio
+import inspect
 import logging
 from typing import Any
 
@@ -31,6 +33,9 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
     ``success`` runs after ``task_function`` returns; ``failure`` runs if it
     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.
 
     Args:
         task_name: The registered name of the task to run.
@@ -48,10 +53,16 @@ def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
 
     try:
         result = task.task_function(*args, **kwargs)
-    except Exception:
+        if inspect.iscoroutine(result):
+            result = asyncio.run(result)
+    except Exception as exc:
+        task.last_result = None
+        task.last_error = exc
         _run_hook(task, "failure", args, kwargs)
         raise
 
+    task.last_result = result
+    task.last_error = None
     _run_hook(task, "success", args, kwargs)
     return result
 

corekit/jobs/task.py

@@ -88,6 +88,8 @@ class Task(abc.ABC):
         """
         self.name = name or self.task_name or type(self).__name__
         self.logger = logging.getLogger(type(self).__module__)
+        self.last_result: Any = None
+        self.last_error: BaseException | None = None
 
     @abc.abstractmethod
     def task_function(self, *args: Any, **kwargs: Any) -> None:
@@ -99,12 +101,18 @@ class Task(abc.ABC):
     def success(self, *args: Any, **kwargs: Any) -> None:
         """
         Called after ``task_function`` returns. Override to add behaviour.
+
+        ``last_result`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
         """
         self.logger.info(f"Task {self.name} completed successfully")
 
     def failure(self, *args: Any, **kwargs: Any) -> None:
         """
         Called when ``task_function`` raises. Override to add behaviour.
+
+        ``last_error`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
         """
         self.logger.error(f"Task {self.name} failed")
 
@@ -119,8 +127,11 @@ class ScheduledTask(Task):
     """
     A task that runs on a schedule.
 
-    The timing attributes are read by whichever adapter schedules the task;
-    nothing here talks to a scheduler itself.
+    ``interval``, ``repeat``, ``timeout``, and ``schedule_delay`` are for the
+    adapter that talks to a scheduler. ``run_task`` does not apply ``timeout``
+    and does not sleep for ``interval`` — wrapping a still-running queue job
+    would change production workers. Copy ``schedule_delay`` per instance so
+    one task cannot mutate the shared class dict.
     """
 
     interval: int | None = None
@@ -133,6 +144,16 @@ class ScheduledTask(Task):
     args: list[Any] | None = None
     kwargs: dict[str, Any] | None = None
 
+    def __init__(self, name: str | None = None) -> None:
+        super().__init__(name)
+        # Class attributes are shared. Replace them on the instance so a later
+        # in-place edit cannot change every other scheduled task.
+        self.schedule_delay = dict(self.schedule_delay)
+        if self.args is not None:
+            self.args = list(self.args)
+        if self.kwargs is not None:
+            self.kwargs = dict(self.kwargs)
+
     def get_start_time(self) -> datetime:
         """
         When the first run should happen.

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