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

corekit/llm/wire.py

@@ -0,0 +1,199 @@
+"""
+Structured OpenAI completion-chunk parsing and tool-call accumulation.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from corekit.llm.enum import WireField
+from corekit.llm.events import UsageEvent
+from corekit.llm.tools.base import ToolCall
+from corekit.utils import safe_dict, safe_string
+from corekit.utils.collections import attr_or_key
+
+__all__ = [
+    "ChoiceDelta",
+    "CompletionTurn",
+    "FunctionCallDelta",
+    "ToolCallAccumulator",
+    "ToolCallDelta",
+    "UsageInfo",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionCallDelta(BaseModel):
+    """
+    Incremental ``function`` fields on a streamed tool-call delta.
+    """
+
+    name: str = ""
+    arguments: str = ""
+
+
+class ToolCallDelta(BaseModel):
+    """
+    One streamed tool-call fragment (may arrive across many chunks).
+    """
+
+    index: int = 0
+    id: str = ""
+    function: FunctionCallDelta = Field(default_factory=FunctionCallDelta)
+
+    @classmethod
+    def from_raw(cls, raw: Any) -> ToolCallDelta | None:
+        """
+        Parse a dict or SDK object into a delta; return None if index is missing.
+        """
+        index = attr_or_key(raw, WireField.INDEX)
+        if index is None:
+            return None
+        function_raw = safe_dict(attr_or_key(raw, WireField.FUNCTION))
+        return cls(
+            index=int(index),
+            id=safe_string(attr_or_key(raw, WireField.ID)),
+            function=FunctionCallDelta(
+                name=safe_string(attr_or_key(function_raw, WireField.NAME)),
+                arguments=safe_string(attr_or_key(function_raw, WireField.ARGUMENTS)),
+            ),
+        )
+
+
+class ToolCallAccumulator(BaseModel):
+    """
+    Merges streamed tool-call deltas for a single index into one call.
+    """
+
+    id: str = ""
+    name: str = ""
+    arguments: str = ""
+
+    def merge(self, delta: ToolCallDelta) -> None:
+        """
+        Append name/argument fragments from one delta.
+        """
+        if delta.id:
+            self.id = delta.id
+        if delta.function.name:
+            self.name += delta.function.name
+        if delta.function.arguments:
+            self.arguments += delta.function.arguments
+
+    def to_tool_call(self) -> ToolCall:
+        """
+        Parse accumulated argument JSON into a ``ToolCall``.
+        """
+        parsed: dict[str, Any] = {}
+        try:
+            parsed = json.loads(self.arguments)
+        except json.JSONDecodeError:
+            logger.warning("Bad tool args for %r: %r", self.name, self.arguments)
+        return ToolCall(id=self.id, name=self.name, arguments=safe_dict(parsed))
+
+
+class ChoiceDelta(BaseModel):
+    """
+    ``choices[0].delta`` fields we care about from one chunk.
+    """
+
+    content: str | None = None
+    reasoning_content: str | None = None
+    tool_calls: list[ToolCallDelta] = Field(default_factory=list)
+    finish_reason: str | None = None
+
+    @classmethod
+    def from_chunk(cls, chunk: Any) -> ChoiceDelta | None:
+        """
+        Extract the first choice's delta (and finish_reason) from a chunk.
+        """
+        choices = attr_or_key(chunk, WireField.CHOICES)
+        if not choices:
+            return None
+        choice = choices[0]
+        delta_raw = attr_or_key(choice, WireField.DELTA)
+        if delta_raw is None:
+            return cls(finish_reason=attr_or_key(choice, WireField.FINISH_REASON))
+
+        tool_calls: list[ToolCallDelta] = []
+        for raw_tc in attr_or_key(delta_raw, WireField.TOOL_CALLS) or []:
+            parsed = ToolCallDelta.from_raw(raw_tc)
+            if parsed is not None:
+                tool_calls.append(parsed)
+
+        return cls(
+            content=attr_or_key(delta_raw, WireField.CONTENT),
+            reasoning_content=attr_or_key(delta_raw, WireField.REASONING_CONTENT),
+            tool_calls=tool_calls,
+            finish_reason=attr_or_key(choice, WireField.FINISH_REASON),
+        )
+
+
+class UsageInfo(BaseModel):
+    """
+    Token usage from a completion chunk or final response.
+    """
+
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+
+    @classmethod
+    def from_chunk(cls, chunk: Any) -> UsageInfo | None:
+        """
+        Read ``usage`` from a chunk when present.
+        """
+        usage = attr_or_key(chunk, WireField.USAGE)
+        if usage is None:
+            return None
+        return cls(
+            prompt_tokens=attr_or_key(usage, WireField.PROMPT_TOKENS),
+            completion_tokens=attr_or_key(usage, WireField.COMPLETION_TOKENS),
+            total_tokens=attr_or_key(usage, WireField.TOTAL_TOKENS),
+        )
+
+    def to_event(self) -> UsageEvent:
+        """
+        Convert to a stream ``UsageEvent``.
+        """
+        return UsageEvent(
+            total_tokens=self.total_tokens,
+            prompt_tokens=self.prompt_tokens,
+            completion_tokens=self.completion_tokens,
+        )
+
+
+class CompletionTurn(BaseModel):
+    """
+    Mutable state accumulated while streaming one ``complete()`` call.
+    """
+
+    tool_calls: dict[int, ToolCallAccumulator] = Field(default_factory=dict)
+    usage: UsageInfo | None = None
+    finish_reason: str | None = None
+    first_token_ms: float | None = None
+
+    def absorb_delta(self, delta: ChoiceDelta) -> None:
+        """
+        Merge one choice delta into this turn.
+        """
+        if delta.finish_reason:
+            self.finish_reason = delta.finish_reason
+        for tool_delta in delta.tool_calls:
+            bucket = self.tool_calls.setdefault(tool_delta.index, ToolCallAccumulator())
+            bucket.merge(tool_delta)
+
+    def absorb_usage(self, usage: UsageInfo | None) -> None:
+        if usage is not None:
+            self.usage = usage
+
+    def parsed_tool_calls(self) -> list[ToolCall]:
+        """
+        Finalize accumulated tool-call indices into ``ToolCall`` values.
+        """
+        return [self.tool_calls[idx].to_tool_call() for idx in sorted(self.tool_calls)]

corekit/observability/__init__.py

@@ -8,10 +8,10 @@ are the same concern -- knowing what a running system is doing.
 
     class Importer(Benchmarkable):
         def run(self) -> None:
-            self.timing()
-            self.info("starting")
+            self.reset_timing()
+            self.timing("started")
             ...
-            self.timing("finished")
+            self.timing("finished")  # total since reset; latest since started
 """
 
 from corekit.observability.benchmarkable import Benchmarkable

corekit/observability/benchmarkable.py

@@ -18,12 +18,26 @@ class Benchmarkable(Loggable):
         super().__init__(*args, **kwargs)
         self._timing = Timer()
 
+    def reset_timing(self) -> None:
+        """
+        Restart the underlying timer for a new unit of work.
+        """
+        self._timing.reset()
+
+    def elapsed_ms(self) -> float:
+        """
+        Milliseconds since start (or last ``reset_timing``), without a split.
+        """
+        return self._timing.elapsed() * 1000
+
     def timing(self, split_name: str | None = None) -> Split:
         """
         Log the time since the last split and return it.
 
-        The log line is unchanged. The return value is for a caller that
-        wants the numbers without parsing that line.
+        ``Split.total`` / ``Split.total_ms`` are since start (or last reset).
+        ``Split.latest`` / ``Split.latest_ms`` are since the previous split.
+        The log line is unchanged. The return value is for a caller that wants
+        the numbers without parsing that line.
         """
         split = self._timing.split(split_name=split_name)
         self.info(str(split))

corekit/observability/timing/split.py

@@ -8,6 +8,20 @@ class Split(BaseModel):
     name: str | None = None
     split_name: str | None = None
 
+    @property
+    def total_ms(self) -> float:
+        """
+        ``total`` in milliseconds.
+        """
+        return self.total * 1000
+
+    @property
+    def latest_ms(self) -> float:
+        """
+        ``latest`` in milliseconds.
+        """
+        return self.latest * 1000
+
     def __str__(self) -> str:
         identifier = ""
         if self.name:

corekit/observability/timing/timer.py

@@ -5,28 +5,50 @@ from corekit.observability.timing.split import Split
 
 
 class Timer:
+    start: float
+    latest: float
+    num: int
+    precision: int
+    name: str
+
     def __init__(self, precision: int = DEFAULT_PRECISION) -> None:
         # perf_counter is monotonic. time.time() can step backwards, which
         # makes a split look negative for no reason the caller can act on.
-        _time = time.perf_counter()
-        self.start = _time
-        self.latest = _time
-        self.num = 0
-        self.name = type(self).__name__
         self.precision = precision if precision > 0 else DEFAULT_PRECISION
+        self.name = type(self).__name__
+        self.reset()
+
+    def reset(self) -> None:
+        """
+        Restart the clock and clear split numbering.
+
+        Use at the start of a new timed unit of work (a request, a model turn,
+        a pipeline stage) so ``total`` measures that unit rather than the
+        object's whole lifetime.
+        """
+        now = time.perf_counter()
+        self.start = now
+        self.latest = now
+        self.num = 0
 
     def _round(self, value: float) -> float:
         return round(value, self.precision)
 
+    def elapsed(self) -> float:
+        """
+        Seconds since start (or last ``reset``), without recording a split.
+        """
+        return self._round(time.perf_counter() - self.start)
+
     def split(self, split_name: str | None = None) -> Split:
-        _time = time.perf_counter()
+        now = time.perf_counter()
         self.num += 1
         split = Split(
             num=self.num,
-            total=self._round(_time - self.start),
-            latest=self._round(_time - self.latest),
+            total=self._round(now - self.start),
+            latest=self._round(now - self.latest),
             name=self.name,
             split_name=split_name,
         )
-        self.latest = _time
+        self.latest = now
         return split

corekit/schemas/__init__.py

@@ -6,5 +6,6 @@ raises where it is introduced rather than somewhere further along.
 """
 
 from corekit.schemas.enum import IntegerEnum, StringEnum, ValidatingEnum
+from corekit.schemas.version import SemanticVersion
 
-__all__ = ["IntegerEnum", "StringEnum", "ValidatingEnum"]
+__all__ = ["IntegerEnum", "SemanticVersion", "StringEnum", "ValidatingEnum"]

corekit/schemas/version.py

@@ -0,0 +1,58 @@
+"""
+Semantic version (``major.minor.patch`` with optional ``-extra``).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Self
+
+from pydantic import BaseModel, Field
+
+from corekit.utils import safe_int, safe_string
+
+__all__ = ["SemanticVersion"]
+
+_VERSION_RE = re.compile(r"^(?P<major>\d+)(?:\.(?P<minor>\d+)(?:\.(?P<patch>\d+)?)?)?(?:-(?P<extra>[A-Za-z0-9._-]+))?$")
+
+
+class SemanticVersion(BaseModel):
+    """
+    Structured ``major.minor.patch`` with an optional ``-extra`` suffix.
+
+    Suitable for filenames, config pins, and other places that need a parsed
+    SemVer-like value without tying to packaging metadata.
+    """
+
+    major: int = Field(ge=0)
+    minor: int = Field(default=0, ge=0)
+    patch: int = Field(default=0, ge=0)
+    extra: str | None = None
+
+    def __str__(self) -> str:
+        version = f"{self.major}.{self.minor}.{self.patch}"
+        if self.extra:
+            return f"{version}-{self.extra}"
+        return version
+
+    def __repr__(self) -> str:
+        return f"SemanticVersion({self})"
+
+    @classmethod
+    def parse(cls, value: SemanticVersion | str | int) -> Self:
+        """
+        Accept a version object, ``\"1.0.0\"``, or a bare major ``1`` (→ ``1.0.0``).
+        """
+        if isinstance(value, SemanticVersion):
+            return value
+        if isinstance(value, int):
+            return cls(major=value)
+        match = _VERSION_RE.fullmatch(safe_string(value))
+        if match is None:
+            raise ValueError(f"Invalid semantic version: {value!r}")
+        return cls(
+            major=safe_int(match.group("major")),
+            minor=safe_int(match.group("minor")),
+            patch=safe_int(match.group("patch")),
+            extra=match.group("extra"),
+        )

corekit/utils/__init__.py

@@ -9,7 +9,7 @@ configuration need.
 """
 
 from corekit.utils.coercion import safe_dict, safe_float, safe_int, safe_list, safe_string, safe_tuple
-from corekit.utils.collections import UNSET, MultiMatch, keygetter, repeated_get, split_list
+from corekit.utils.collections import UNSET, MultiMatch, attr_or_key, keygetter, repeated_get, split_list
 from corekit.utils.ids import (
     SHORTCODE_CHARS,
     generate_session_token,
@@ -19,7 +19,7 @@ from corekit.utils.ids import (
 )
 from corekit.utils.payload import Payload, decode_payload, encode_payload
 from corekit.utils.raise_exc import raise_exc
-from corekit.utils.text import join_lines, list_to_english, sanitize_filename
+from corekit.utils.text import join_lines, list_to_english, sanitize_filename, truncate
 from corekit.utils.time import isoformat_now, parse_docker_timestamp, time_now, timedelta_now, timestamp_now
 from corekit.utils.validators import false_validator, true_validator
 from corekit.utils.void import void
@@ -29,6 +29,7 @@ __all__ = [
     "UNSET",
     "MultiMatch",
     "Payload",
+    "attr_or_key",
     "decode_payload",
     "encode_payload",
     "false_validator",
@@ -55,5 +56,6 @@ __all__ = [
     "timedelta_now",
     "timestamp_now",
     "true_validator",
+    "truncate",
     "void",
 ]

corekit/utils/collections.py

@@ -10,7 +10,7 @@ missing or the wrong type.
 from copy import deepcopy
 from typing import Any, Callable
 
-__all__ = ["MultiMatch", "keygetter", "repeated_get", "split_list"]
+__all__ = ["MultiMatch", "attr_or_key", "keygetter", "repeated_get", "split_list"]
 
 KEY_SEPARATOR = "."
 
@@ -25,6 +25,21 @@ def split_list(items: list[Any], index: int) -> tuple[list[Any], list[Any]]:
     return items[:index], items[index:]
 
 
+def attr_or_key(obj: Any, name: str) -> Any:
+    """
+    Read ``name`` from a mapping or an object attribute.
+
+    Returns ``None`` when ``obj`` is ``None``, the key is missing, or the
+    attribute is absent. Useful for SDK payloads that arrive as either dicts
+    or attribute-bearing chunk objects.
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
 class MultiMatch(dict[str, Any]):
     """
     The result of a path step that matched more than one key.

corekit/utils/text.py

@@ -2,13 +2,14 @@
 String assembly helpers.
 
 Small formatters for turning collections into text a human will read -- log
-lines, notification bodies, error messages -- plus filename sanitization.
+lines, notification bodies, error messages -- plus filename sanitization and
+length limits.
 """
 
 import re
 from typing import Any, Literal
 
-__all__ = ["join_lines", "list_to_english", "sanitize_filename"]
+__all__ = ["join_lines", "list_to_english", "sanitize_filename", "truncate"]
 
 FALLBACK_FILENAME = "unnamed"
 _UNSAFE_CHARS = re.compile(r"[^a-z0-9\-]")
@@ -43,6 +44,24 @@ def list_to_english(items: list[str], ending: Literal["and", "or"] | None = None
     return f"{buffer}, {ending} {last}"
 
 
+def truncate(text: str, limit: int, *, suffix: str = "") -> str:
+    """
+    Cut ``text`` to at most ``limit`` characters, appending ``suffix`` when cut.
+
+    ``suffix`` counts toward ``limit``, so the returned string is never longer
+    than ``limit`` (unless ``suffix`` itself is longer than ``limit``, in which
+    case ``suffix`` is returned truncated to ``limit``).
+    """
+    if limit <= 0:
+        return ""
+    if len(text) <= limit:
+        return text
+    if len(suffix) >= limit:
+        return suffix[:limit]
+    keep = limit - len(suffix)
+    return text[:keep] + suffix
+
+
 def sanitize_filename(raw: str, fallback: str = FALLBACK_FILENAME) -> str:
     """
     Reduce a string to lowercase kebab-case safe for use as a filename stem.

{python_corekit-0.3.0.dist-info → python_corekit-0.4.1.dist-info}/METADATA

@@ -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.1
+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.
@@ -88,6 +90,29 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Exceptionator
+
+Catch an exception, run one action, then rethrow so the existing failure path
+still happens. Built-in actions are no-op and log-traceback; apps supply their
+own (persist, notify, …).
+
+```python
+from corekit.exceptionator import (
+    Exceptionator,
+    ExceptionatorMiddleware,
+    LogTracebackAction,
+    install_run_task_hook,
+    set_process_exceptionator,
+)
+
+exceptionator = Exceptionator(LogTracebackAction(), service="api")
+set_process_exceptionator(exceptionator)
+install_run_task_hook(exceptionator)  # optional; run_task captures with task name
+```
+
+`ExceptionatorMiddleware` is raw ASGI (not `BaseHTTPMiddleware`). With no
+`run_task` hook installed, jobs behave as in 0.4.0.
+
 ## Assembling an application
 
 `Application` is a plain `FastAPI` subclass — every constructor argument,
@@ -281,6 +306,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 +445,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
 ```