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

corekit/llm/messages.py

@@ -0,0 +1,173 @@
+"""
+OpenAI-shaped chat messages — base plus role-specific subclasses.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from corekit.llm.enum import ContentPartType, Role, ToolCallType, WireField
+from corekit.llm.tools.base import ToolCall
+
+__all__ = [
+    "AssistantMessage",
+    "ChatTurn",
+    "Message",
+    "SystemMessage",
+    "ToolMessage",
+    "UserMessage",
+]
+
+from corekit.utils import safe_list
+
+
+class Message(BaseModel):
+    """
+    Shared chat-turn base. Prefer a role-specific subclass for construction.
+    """
+
+    role: Role
+    content: str
+
+    def format(self, *, internal: bool = False) -> dict[str, Any]:
+        """
+        Render as an OpenAI chat-message dict.
+
+        ``internal`` is reserved for subclasses that add provider-specific
+        fields (e.g. assistant ``reasoning_content``).
+        """
+        del internal  # base turns ignore it
+        return {WireField.ROLE: self.role.value, WireField.CONTENT: self.content}
+
+    @classmethod
+    def as_wire(
+        cls,
+        messages: Sequence[ChatTurn],
+        *,
+        internal: bool = False,
+    ) -> list[dict[str, Any]]:
+        """
+        Normalize ``Message`` instances and raw mappings to OpenAI wire dicts.
+        """
+        wire: list[dict[str, Any]] = []
+        for message in messages:
+            if isinstance(message, Message):
+                wire.append(message.format(internal=internal))
+            else:
+                wire.append(dict(message))
+        return wire
+
+    def prettify(self) -> str:
+        """
+        Compact debug string for logs and hashes.
+        """
+        return f"[{self.role}]: {self.content}"
+
+
+class SystemMessage(Message):
+    """
+    System instruction turn.
+    """
+
+    role: Role = Field(default=Role.SYSTEM, frozen=True)
+
+
+class UserMessage(Message):
+    """
+    User turn, optionally multimodal via ``images``.
+    """
+
+    role: Role = Field(default=Role.USER, frozen=True)
+    images: list[str] | None = None  # base64 data URIs or URLs
+
+    def format(self, *, internal: bool = False) -> dict[str, Any]:
+        del internal
+        message: dict[str, Any] = {WireField.ROLE: self.role.value}
+        if self.images:
+            message[WireField.CONTENT] = self._image_content_parts()
+        else:
+            message[WireField.CONTENT] = self.content
+        return message
+
+    def prettify(self) -> str:
+        image_note = f" [+{len(self.images)} image(s)]" if self.images else ""
+        return f"[{self.role}]: {self.content}{image_note}"
+
+    def _image_content_parts(self) -> list[dict[str, Any]]:
+        parts: list[dict[str, Any]] = [
+            {
+                WireField.TYPE: ContentPartType.IMAGE_URL,
+                WireField.IMAGE_URL: {WireField.URL: img},
+            }
+            for img in safe_list(self.images)
+        ]
+        parts.append({WireField.TYPE: ContentPartType.TEXT, WireField.TEXT: self.content})
+        return parts
+
+
+class AssistantMessage(Message):
+    """
+    Assistant turn — optional prior reasoning and/or tool calls.
+    """
+
+    role: Role = Field(default=Role.ASSISTANT, frozen=True)
+    reasoning: str | None = None  # prior thinking (internal endpoints)
+    tool_calls: list[ToolCall] | None = None
+
+    def format(self, *, internal: bool = False) -> dict[str, Any]:
+        """
+        When ``internal`` is True and reasoning is set, include
+        ``reasoning_content`` for llama.cpp-style servers. Other providers
+        reject that field.
+        """
+        message: dict[str, Any] = {
+            WireField.ROLE: self.role.value,
+            WireField.CONTENT: self.content,
+        }
+        if self.tool_calls:
+            message[WireField.TOOL_CALLS] = [_tool_call_wire(call) for call in self.tool_calls]
+        if internal and self.reasoning:
+            message[WireField.REASONING_CONTENT] = self.reasoning
+        return message
+
+    @classmethod
+    def with_tools(cls, content: str, tool_calls: list[ToolCall]) -> AssistantMessage:
+        return cls(content=content, tool_calls=tool_calls)
+
+
+class ToolMessage(Message):
+    """
+    Tool-result turn; ``tool_call_id`` links back to the assistant call.
+    """
+
+    role: Role = Field(default=Role.TOOL, frozen=True)
+    tool_call_id: str
+
+    def format(self, *, internal: bool = False) -> dict[str, Any]:
+        del internal
+        return {
+            WireField.ROLE: self.role.value,
+            WireField.CONTENT: self.content,
+            WireField.TOOL_CALL_ID: self.tool_call_id,
+        }
+
+    @classmethod
+    def from_result(cls, tool_call_id: str, content: str) -> ToolMessage:
+        return cls(content=content, tool_call_id=tool_call_id)
+
+
+def _tool_call_wire(call: ToolCall) -> dict[str, Any]:
+    return {
+        WireField.ID: call.id,
+        WireField.TYPE: ToolCallType.FUNCTION,
+        WireField.FUNCTION: {
+            WireField.NAME: call.name,
+            WireField.ARGUMENTS: call.arguments_json(),
+        },
+    }
+
+
+ChatTurn = Message | Mapping[str, Any]

corekit/llm/prompts/__init__.py

@@ -0,0 +1,19 @@
+"""
+Mountable prompt loader for versioned ``.txt`` trees.
+"""
+
+from corekit.llm.prompts.enum import PromptFileRole, PromptKind, ThinkingLevel
+from corekit.llm.prompts.exceptions import PromptError, PromptNotFoundError
+from corekit.llm.prompts.loader import DEFAULT_PROMPT_VERSION, PromptLoader
+from corekit.llm.prompts.template import PromptTemplate
+
+__all__ = [
+    "DEFAULT_PROMPT_VERSION",
+    "PromptError",
+    "PromptFileRole",
+    "PromptKind",
+    "PromptLoader",
+    "PromptNotFoundError",
+    "PromptTemplate",
+    "ThinkingLevel",
+]

corekit/llm/prompts/enum.py

@@ -0,0 +1,54 @@
+"""
+Prompt-tree enumerations (category, file role, thinking budget).
+"""
+
+from corekit.schemas import StringEnum
+
+__all__ = ["PromptFileRole", "PromptKind", "ThinkingLevel"]
+
+
+class PromptKind(StringEnum):
+    """
+    Top-level folders under a mounted prompt root.
+
+    Custom categories are fine — pass a plain string to ``PromptLoader`` instead.
+    """
+
+    CLASSIFICATION = "classification"
+    COMMON = "common"
+    CONVERSATION = "conversation"
+    DESCRIPTION = "description"
+    DOCUMENT = "document"
+    EVALUATION = "evaluation"
+    EXTRACTION = "extraction"
+    MEMORY = "memory"
+    RERANKING = "reranking"
+    SUMMARIZATION = "summarization"
+    TRANSFORMATION = "transformation"
+
+
+class PromptFileRole(StringEnum):
+    """
+    Filename role prefix: ``{role}-v{version}.txt``.
+    """
+
+    SYSTEM = "system"
+    USER = "user"
+    FRAGMENT = "fragment"
+
+
+class ThinkingLevel(StringEnum):
+    """
+    Which ``common/thinking_*`` fragment to append to the system prompt.
+    """
+
+    NONE = "none"
+    LOW = "low"
+    DEFAULT = "default"
+    HIGH = "high"
+
+    def is_none(self) -> bool:
+        return self == ThinkingLevel.NONE
+
+    def fragment_name(self) -> str:
+        return f"thinking_{self.value}"

corekit/llm/prompts/exceptions.py

@@ -0,0 +1,22 @@
+"""
+Prompt loader exceptions.
+"""
+
+from corekit.exceptions import InternalCoreException, Retryability
+
+__all__ = ["PromptError", "PromptNotFoundError"]
+
+
+class PromptError(InternalCoreException):
+    """
+    Prompt loader configuration or resolution failure.
+    """
+
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
+
+class PromptNotFoundError(PromptError):
+    """
+    Expected prompt file is missing under the mounted root.
+    """

corekit/llm/prompts/loader.py

@@ -0,0 +1,139 @@
+"""
+Filesystem prompt loader — mount any compatible versioned ``.txt`` tree.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from corekit.llm.prompts.enum import PromptFileRole, PromptKind, ThinkingLevel
+from corekit.llm.prompts.exceptions import PromptError, PromptNotFoundError
+from corekit.llm.prompts.template import PromptTemplate
+from corekit.observability import Benchmarkable
+from corekit.schemas import SemanticVersion
+
+__all__ = ["PromptLoader"]
+
+# ``{COMMON:confidence_calibration_scale}`` → fragment body (one pass).
+_COMMON_INCLUDE = re.compile(r"\{COMMON:([a-z][a-z0-9_]*)\}")
+
+DEFAULT_PROMPT_VERSION = SemanticVersion(major=1, minor=0, patch=0)
+
+VersionLike = SemanticVersion | str | int
+KindLike = PromptKind | str
+
+
+class PromptLoader(Benchmarkable):
+    """
+    Read versioned prompt files from a mounted directory tree.
+
+    Expected layout::
+
+        {root}/
+          extraction/entities/system-v1.0.0.txt
+          extraction/entities/user-v1.0.0.txt
+          common/thinking_default/fragment-v1.0.0.txt
+
+    Point ``root`` at any directory that follows this convention::
+
+        loader = PromptLoader("/path/to/prompts")
+        tmpl = loader.load("extraction", "entities", system="1.0.0", user="1.0.0")
+    """
+
+    def __init__(self, root: str | Path) -> None:
+        super().__init__()
+        self.root = Path(root).expanduser().resolve()
+        if not self.root.is_dir():
+            raise PromptError(f"Prompt root is not a directory: {self.root}")
+
+    def path_for(
+        self,
+        kind: KindLike,
+        name: str,
+        role: PromptFileRole | str,
+        version: VersionLike = DEFAULT_PROMPT_VERSION,
+    ) -> Path:
+        """
+        Resolve ``{root}/{kind}/{name}/{role}-v{version}.txt`` without reading.
+        """
+        ver = SemanticVersion.parse(version)
+        return self.root / str(kind) / name / f"{str(role)}-v{ver}.txt"
+
+    def read(
+        self,
+        kind: KindLike,
+        name: str,
+        role: PromptFileRole | str,
+        version: VersionLike = DEFAULT_PROMPT_VERSION,
+    ) -> str:
+        """
+        Read and strip a single prompt file.
+        """
+        path = self.path_for(kind, name, role, version)
+        try:
+            return path.read_text(encoding="utf-8").strip()
+        except FileNotFoundError as exc:
+            raise PromptNotFoundError(f"Prompt file not found: {path}") from exc
+        except OSError as exc:
+            raise PromptError(f"Failed to read prompt file: {path}") from exc
+
+    def load_fragment(
+        self,
+        name: str,
+        version: VersionLike = DEFAULT_PROMPT_VERSION,
+    ) -> str:
+        """
+        Load ``common/{name}/fragment-v….txt``.
+        """
+        return self.read(
+            kind=PromptKind.COMMON,
+            name=name,
+            role=PromptFileRole.FRAGMENT,
+            version=version,
+        )
+
+    def load(
+        self,
+        kind: KindLike,
+        name: str,
+        *,
+        system: VersionLike = DEFAULT_PROMPT_VERSION,
+        user: VersionLike | None = DEFAULT_PROMPT_VERSION,
+        thinking: ThinkingLevel = ThinkingLevel.DEFAULT,
+    ) -> PromptTemplate:
+        """
+        Load system (+ optional user) files, inject ``{COMMON:…}`` fragments,
+        and append a thinking-budget fragment unless ``thinking`` is ``NONE``.
+
+        Pass ``user=None`` when there is no user template file; ``format_user``
+        then expects a raw ``content=`` kwarg.
+        """
+        self.timing()
+        system_prompt = self._inject_common(self.read(kind, name, PromptFileRole.SYSTEM, system))
+
+        if not thinking.is_none():
+            system_prompt = f"{system_prompt}\n\n{self.load_fragment(thinking.fragment_name())}"
+
+        user_prompt: str | None = None
+        if user is not None:
+            user_prompt = self.read(kind, name, PromptFileRole.USER, user)
+
+        template = PromptTemplate(
+            kind=str(kind),
+            name=name,
+            system=system_prompt,
+            user=user_prompt,
+        )
+        self.timing("prompt_loaded")
+        return template
+
+    def _inject_common(self, text: str) -> str:
+        """
+        Replace ``{COMMON:name}`` tokens with the matching fragment body.
+        """
+
+        def _replace(match: re.Match[str]) -> str:
+            return self.load_fragment(match.group(1))
+
+        return _COMMON_INCLUDE.sub(_replace, text)

corekit/llm/prompts/template.py

@@ -0,0 +1,53 @@
+"""
+Loaded system + user prompt pair with ``{variable}`` user formatting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from corekit.llm.messages import Message, SystemMessage, UserMessage
+
+__all__ = ["PromptTemplate"]
+
+
+@dataclass(frozen=True)
+class PromptTemplate:
+    """
+    A resolved prompt: system text plus an optional user template.
+
+    User templates use ``str.format`` placeholders (``{text}``, ``{style}``, …).
+    Brace-escape values that contain ``{`` / ``}`` so caller content cannot
+    corrupt the template. When ``user`` is ``None``, ``format_user`` returns
+    the caller's raw ``content`` kwarg.
+    """
+
+    kind: str
+    name: str
+    system: str
+    user: str | None = None
+    temperature: float = 0.3
+
+    def format_user(self, **kwargs: Any) -> str:
+        """
+        Fill the user template, or return ``kwargs[\"content\"]`` when there is none.
+
+        Values are stringified and substituted as-is. Literal braces in the
+        *template* file must be doubled (``{{`` / ``}}``) per ``str.format``.
+        """
+        if self.user is None:
+            if "content" not in kwargs:
+                raise KeyError("Prompt has no user template; pass content=...")
+            return str(kwargs["content"])
+
+        return self.user.format(**{key: str(value) for key, value in kwargs.items()})
+
+    def messages(self, **kwargs: Any) -> list[Message]:
+        """
+        Build OpenAI-shaped system + user turns.
+        """
+        return [
+            SystemMessage(content=self.system),
+            UserMessage(content=self.format_user(**kwargs)),
+        ]

corekit/llm/protocols.py

@@ -0,0 +1,65 @@
+"""
+Protocols the tool loop injects rather than owning.
+
+For a ready-made HTTP implementation, use ``ChatCompletionsClient`` — you only
+need a custom ``ChatClient`` when wrapping an existing SDK or non-HTTP backend.
+"""
+
+from collections.abc import AsyncIterator, Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from corekit.llm.messages import ChatTurn
+
+__all__ = ["ChatClient", "MetricsRecorder"]
+
+
+@runtime_checkable
+class ChatClient(Protocol):
+    """
+    Async OpenAI-compatible chat completions.
+
+    ``ToolLoop`` always calls ``complete(..., stream=True)`` and ``async for``s
+    the result. Messages may be ``Message`` instances or raw wire dicts.
+
+    Prefer ``corekit.llm.ChatCompletionsClient`` unless you already have a
+    stream from another library.
+    """
+
+    def complete(
+        self,
+        messages: Sequence[ChatTurn],
+        *,
+        tools: Sequence[Mapping[str, Any]] | None = None,
+        model: str | None = None,
+        stream: bool = True,
+        **kwargs: Any,
+    ) -> AsyncIterator[Any]:
+        """
+        Stream one completion turn (``stream=True``).
+        """
+        ...
+
+
+@runtime_checkable
+class MetricsRecorder(Protocol):
+    """
+    Optional callback after each streamed turn. Implementations may no-op.
+    """
+
+    def record(
+        self,
+        *,
+        model: str | None = None,
+        streamed: bool = True,
+        succeeded: bool = True,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        total_tokens: int | None = None,
+        time_to_first_token_ms: float | None = None,
+        total_duration_ms: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Record one completion attempt.
+        """
+        ...

corekit/llm/streaming.py

@@ -0,0 +1,149 @@
+"""
+Think-tag streaming helpers for llama.cpp-style ``<think>`` content.
+"""
+
+import re
+from collections.abc import Generator, Iterator
+from enum import Enum
+from typing import NamedTuple
+
+from corekit.llm.events import StreamEvent, TextEvent, ThinkingEvent
+
+__all__ = [
+    "THINK_PATTERN",
+    "ModelStreamingState",
+    "ThinkingMarker",
+    "ThinkingMarkerPair",
+    "strip_thinking",
+]
+
+THINK_PATTERN = re.compile(r"<think>.*?</think>\s*", re.DOTALL)
+
+
+def strip_thinking(text: str) -> str:
+    """
+    Remove complete ``<think>…</think>`` blocks from a finished string.
+    """
+    return THINK_PATTERN.sub("", text).strip()
+
+
+class ThinkingMarkerPair(NamedTuple):
+    start: str
+    end: str
+
+
+class ThinkingMarker(Enum):
+    """
+    Delimiter pairs for thinking regions in model content.
+    """
+
+    XML_THINK = ThinkingMarkerPair(start="<think>", end="</think>")
+
+    @property
+    def start(self) -> str:
+        return self.value.start
+
+    @property
+    def end(self) -> str:
+        return self.value.end
+
+
+class ModelStreamingState:
+    """
+    Tracks ``<think>…</think>`` (or other marker) parse state across chunks.
+    """
+
+    def __init__(self, marker: ThinkingMarker = ThinkingMarker.XML_THINK) -> None:
+        self.marker = marker
+        self.inside = False
+        self.text_buffer = ""
+        self.think_buffer = ""
+        self._complete_buffer = ""
+        self._pending = ""  # held-back prefix of an open/close marker
+
+    def format(self) -> str:
+        return (
+            f"ModelStreamingState(text={self.text_buffer!r}, "
+            f"think={self.think_buffer!r}, complete={self._complete_buffer!r})"
+        )
+
+    def feed(self, delta: str) -> Iterator[StreamEvent]:
+        """
+        Parse one content delta; yield text / thinking events and update buffers.
+        """
+        buf = self._pending + delta
+        self._pending = ""
+
+        while buf:
+            if self.inside:
+                buf = yield from self._feed_inside(buf)
+            else:
+                buf = yield from self._feed_outside(buf)
+
+    def _feed_outside(self, buf: str) -> Generator[StreamEvent, None, str]:
+        """
+        Emit text until a start marker; return leftover buffer.
+        """
+        idx = buf.find(self.marker.start)
+        if idx != -1:
+            before = buf[:idx]
+            if before:
+                self._append_text(before)
+                yield TextEvent(content=before)
+            self.inside = True
+            return buf[idx + len(self.marker.start) :]
+
+        partial = self._partial_tag_suffix(buf, self.marker.start)
+        if partial:
+            emit = buf[: -len(partial)]
+            if emit:
+                self._append_text(emit)
+                yield TextEvent(content=emit)
+            self._pending = partial
+        else:
+            self._append_text(buf)
+            yield TextEvent(content=buf)
+        return ""
+
+    def _feed_inside(self, buf: str) -> Generator[StreamEvent, None, str]:
+        """
+        Emit thinking until an end marker; return leftover buffer.
+        """
+        idx = buf.find(self.marker.end)
+        if idx != -1:
+            thought = buf[:idx]
+            if thought:
+                self._append_think(thought)
+                yield ThinkingEvent(content=thought)
+            self.inside = False
+            return buf[idx + len(self.marker.end) :].lstrip()
+
+        partial = self._partial_tag_suffix(buf, self.marker.end)
+        if partial:
+            emit = buf[: -len(partial)]
+            if emit:
+                self._append_think(emit)
+                yield ThinkingEvent(content=emit)
+            self._pending = partial
+        else:
+            self._append_think(buf)
+            yield ThinkingEvent(content=buf)
+        return ""
+
+    def _append_text(self, new: str) -> None:
+        self.text_buffer += new
+        self._complete_buffer += new
+
+    def _append_think(self, new: str) -> None:
+        self.think_buffer += new
+        self._complete_buffer += new
+
+    @staticmethod
+    def _partial_tag_suffix(text: str, tag: str) -> str:
+        """
+        Longest non-empty suffix of ``text`` that is a prefix of ``tag``.
+        """
+        for i in range(min(len(tag) - 1, len(text)), 0, -1):
+            if text.endswith(tag[:i]):
+                return text[-i:]
+        return ""

corekit/llm/tools/__init__.py

@@ -0,0 +1,19 @@
+"""
+Tool vocabulary, registry, and detectors.
+
+``ToolLoop`` lives in ``corekit.llm.tools.loop`` and is re-exported from
+``corekit.llm`` — importing it here would cycle through ``events``.
+"""
+
+from corekit.llm.tools.base import Tool, ToolCall, ToolResult
+from corekit.llm.tools.detection import MAX_TOOL_ITERATIONS, ToolCallLoopDetector
+from corekit.llm.tools.registry import ToolRegistry
+
+__all__ = [
+    "MAX_TOOL_ITERATIONS",
+    "Tool",
+    "ToolCall",
+    "ToolCallLoopDetector",
+    "ToolRegistry",
+    "ToolResult",
+]