python-corekit 0.3.0__tar.gz → 0.4.0__tar.gz

{python_corekit-0.3.0/python_corekit.egg-info → python_corekit-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.3.0
-Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, and ETL
+Version: 0.4.0
+Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, ETL, and LLM chat/tool primitives
 Author: Steven Jacobsen
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/stevejaker/corekit
@@ -18,6 +18,7 @@ License-File: LICENSE
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: pydantic-settings<3,>=2.0
 Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: starlette<0.47,>=0.40
 Requires-Dist: sqlmodel<0.1,>=0.0.16
 Requires-Dist: SQLAlchemy<3,>=2.0
 Requires-Dist: redis<7,>=5.0
@@ -37,7 +38,8 @@ Dynamic: license-file
 
 Shared foundations for Python projects: structured logging, benchmarking,
 registries, a FastAPI application with routers and handlers, SQL statements and
-migrations, background tasks, an in-memory record store, and ETL scaffolding.
+migrations, background tasks, an in-memory record store, ETL scaffolding, and
+OpenAI-shaped chat / tool-loop primitives.
 
 Requires Python 3.11+.
 
@@ -55,7 +57,7 @@ extras to remember, and no import that fails because something was left out.
 Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.3.0
+python-corekit~=0.4.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -281,6 +283,32 @@ ceiling, not 9,999 threads.
 Failures propagate by default. Pass `raise_on_error=False` to log and skip them
 instead, which loses results silently and so is opt-in.
 
+## LLM chat and tools
+
+OpenAI-shaped messages, a tool registry, an agentic loop, and a thin
+``ChatCompletionsClient`` (a ``BaseApiClient``) for any OpenAI-compatible
+server — llama.cpp, vLLM, OpenAI, and so on. Not a multi-provider generation
+facade.
+
+```python
+from corekit.llm import ChatCompletionsClient, PromptLoader, ToolLoop, ToolRegistry
+
+client = ChatCompletionsClient("http://localhost:8080/v1", model="local")
+prompts = PromptLoader("/path/to/prompts")  # mount any compatible tree
+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="short")):
+    ...
+```
+
+``PromptLoader`` reads versioned ``.txt`` files from a directory you point at
+(``{kind}/{name}/{role}-v{version}.txt``, plus ``common/`` fragments). Prompt
+*text* stays with the consumer — corekit only ships the loader. See
+`docs/LLM_EXTRACTION.md`.
+
 ## HTTP clients
 
 ```python
@@ -394,6 +422,7 @@ corekit/
 
   api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/
+  llm/                             messages, tools, agentic loop (no GenerationClient)
 
   events/  log_monitor/            built on the capabilities above
 ```

{python_corekit-0.3.0 → python_corekit-0.4.0}/README.md

@@ -2,7 +2,8 @@
 
 Shared foundations for Python projects: structured logging, benchmarking,
 registries, a FastAPI application with routers and handlers, SQL statements and
-migrations, background tasks, an in-memory record store, and ETL scaffolding.
+migrations, background tasks, an in-memory record store, ETL scaffolding, and
+OpenAI-shaped chat / tool-loop primitives.
 
 Requires Python 3.11+.
 
@@ -20,7 +21,7 @@ extras to remember, and no import that fails because something was left out.
 Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.3.0
+python-corekit~=0.4.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -246,6 +247,32 @@ ceiling, not 9,999 threads.
 Failures propagate by default. Pass `raise_on_error=False` to log and skip them
 instead, which loses results silently and so is opt-in.
 
+## LLM chat and tools
+
+OpenAI-shaped messages, a tool registry, an agentic loop, and a thin
+``ChatCompletionsClient`` (a ``BaseApiClient``) for any OpenAI-compatible
+server — llama.cpp, vLLM, OpenAI, and so on. Not a multi-provider generation
+facade.
+
+```python
+from corekit.llm import ChatCompletionsClient, PromptLoader, ToolLoop, ToolRegistry
+
+client = ChatCompletionsClient("http://localhost:8080/v1", model="local")
+prompts = PromptLoader("/path/to/prompts")  # mount any compatible tree
+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="short")):
+    ...
+```
+
+``PromptLoader`` reads versioned ``.txt`` files from a directory you point at
+(``{kind}/{name}/{role}-v{version}.txt``, plus ``common/`` fragments). Prompt
+*text* stays with the consumer — corekit only ships the loader. See
+`docs/LLM_EXTRACTION.md`.
+
 ## HTTP clients
 
 ```python
@@ -359,6 +386,7 @@ corekit/
 
   api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/
+  llm/                             messages, tools, agentic loop (no GenerationClient)
 
   events/  log_monitor/            built on the capabilities above
 ```

{python_corekit-0.3.0 → python_corekit-0.4.0}/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",

{python_corekit-0.3.0 → python_corekit-0.4.0}/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)

python_corekit-0.4.0/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

python_corekit-0.4.0/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",
+]

python_corekit-0.4.0/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