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

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

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.
+        """
+        ...