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

corekit/http/__init__.py

@@ -27,6 +27,7 @@ from corekit.http.exceptions import (
 from corekit.http.exponential_backoff import ExponentialBackoff
 from corekit.http.response import BaseApiResponse
 from corekit.http.status import HTTPStatusCode
+from corekit.http.stream import SseDecoder, SseJsonDecoder, SseTextDecoder, StreamDecoder
 
 __all__ = [
     "BadGatewayException",
@@ -42,6 +43,10 @@ __all__ = [
     "InternalServerErrorException",
     "NotFoundException",
     "ServiceUnavailableException",
+    "SseDecoder",
+    "SseJsonDecoder",
+    "SseTextDecoder",
+    "StreamDecoder",
     "TooManyRequestsException",
     "UnauthorizedException",
     "UnprocessableEntityException",

corekit/http/client.py

@@ -2,9 +2,10 @@
 A small HTTP client with retries.
 
 ``BaseHttpClient`` is the transport: relative paths, optional strict URL
-checking, and retries for statuses the typed HTTP exceptions mark as
-retryable. Subclass ``BaseApiClient`` when the client always talks to one
-API and a foreign absolute URL should be a bug.
+checking, retries for statuses the typed HTTP exceptions mark as
+retryable, and ``stream_request`` for SSE / chunked bodies. Subclass
+``BaseApiClient`` when the client always talks to one API and a foreign
+absolute URL should be a bug.
 
     class GithubClient(BaseApiClient):
         '''
@@ -27,6 +28,8 @@ Every response comes back as a ``BaseApiResponse``, so callers see one shape
 regardless of what the endpoint returned.
 """
 
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from http import HTTPMethod
 from typing import Any
 from urllib.parse import urljoin, urlsplit, urlunsplit
@@ -182,6 +185,34 @@ class BaseHttpClient(Benchmarkable):
             self.warning(f"{method} {_without_query(target)} returned {raw.status_code}; retrying")
             await backoff.async_wait()
 
+    @asynccontextmanager
+    async def stream_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> AsyncIterator[httpx.Response]:
+        """
+        Open a streaming response and yield the raw ``httpx.Response``.
+
+        Holds the connection for the life of the ``async with`` block. Unlike
+        ``request``, the body is not buffered into a ``BaseApiResponse`` — the
+        caller reads it (for example with ``aiter_lines`` for SSE). Retries are
+        not applied: a mid-stream failure cannot be replayed safely.
+        """
+        if method not in self.supported_methods:
+            raise UnsupportedMethodError(method)
+
+        target = self._build_url(url)
+        headers = dict(self.headers)
+        extra_headers: dict[str, Any] | None = kwargs.pop("headers", None)
+        if extra_headers:
+            headers.update(extra_headers)
+
+        if self._http_client is not None:
+            async with self._http_client.stream(str(method), target, headers=headers, **kwargs) as response:
+                yield response
+            return
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            async with client.stream(str(method), target, headers=headers, **kwargs) as response:
+                yield response
+
     @allow_sync
     async def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
         return await self.request(HTTPMethod.GET, url, **kwargs)

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/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"