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

{python_corekit-0.3.0 → python_corekit-0.4.1}/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.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
 ```

{python_corekit-0.3.0 → python_corekit-0.4.1}/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.
@@ -53,6 +54,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,
@@ -246,6 +270,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 +409,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.4.1/corekit/exceptionator/__init__.py

@@ -0,0 +1,68 @@
+"""
+Process-wide exception capture: catch, run one action, rethrow.
+
+Product concerns (Postgres, ntfy, prompts) stay in the installing application.
+This package owns the wrapper, built-in actions, fingerprinting, ASGI middleware,
+and the ``run_task`` hook point.
+"""
+
+from corekit.exceptionator.actions import (
+    ExceptionatorAction,
+    LogTracebackAction,
+    NoOpAction,
+)
+from corekit.exceptionator.asgi import (
+    ExceptionatorMiddleware,
+    get_process_exceptionator,
+    record_http_exception,
+    set_process_exceptionator,
+    should_record_http_exception,
+)
+from corekit.exceptionator.exceptionator import Exceptionator
+from corekit.exceptionator.fingerprint import ExceptionFingerprint, ExceptionText
+from corekit.exceptionator.guard import (
+    begin_handling,
+    end_handling,
+    handling_active,
+    is_captured,
+    mark_captured,
+)
+from corekit.exceptionator.jobs import (
+    clear_run_task_hook,
+    get_run_task_hook,
+    install_run_task_hook,
+)
+from corekit.exceptionator.models import (
+    CapturedException,
+    ExceptionatorActionName,
+    ExceptionContext,
+    ExceptionSource,
+    build_captured,
+)
+
+__all__ = [
+    "CapturedException",
+    "ExceptionContext",
+    "ExceptionFingerprint",
+    "ExceptionSource",
+    "ExceptionText",
+    "Exceptionator",
+    "ExceptionatorAction",
+    "ExceptionatorActionName",
+    "ExceptionatorMiddleware",
+    "LogTracebackAction",
+    "NoOpAction",
+    "begin_handling",
+    "build_captured",
+    "clear_run_task_hook",
+    "end_handling",
+    "get_process_exceptionator",
+    "get_run_task_hook",
+    "handling_active",
+    "install_run_task_hook",
+    "is_captured",
+    "mark_captured",
+    "record_http_exception",
+    "set_process_exceptionator",
+    "should_record_http_exception",
+]

python_corekit-0.4.1/corekit/exceptionator/actions.py

@@ -0,0 +1,46 @@
+"""
+Built-in Exceptionator actions.
+"""
+
+from __future__ import annotations
+
+from corekit.exceptionator.models import CapturedException
+from corekit.observability.loggable import Loggable
+
+__all__ = ["ExceptionatorAction", "LogTracebackAction", "NoOpAction"]
+
+
+class ExceptionatorAction(Loggable):
+    """
+    Work performed after an exception is captured and before it continues.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Perform the action. Must not raise.
+        """
+        raise NotImplementedError
+
+
+class NoOpAction(ExceptionatorAction):
+    """
+    Catch and continue. Records nothing and publishes nothing.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Do nothing with the captured exception.
+        """
+        return None
+
+
+class LogTracebackAction(ExceptionatorAction):
+    """
+    Write the message and traceback. Does not store or notify.
+    """
+
+    def run(self, captured: CapturedException) -> None:
+        """
+        Log the incident text.
+        """
+        self.error(f"{captured.service} {captured.exception_type}: {captured.message}\n{captured.traceback_text}")

python_corekit-0.4.1/corekit/exceptionator/asgi.py

@@ -0,0 +1,115 @@
+"""
+ASGI middleware and HTTP helpers for Exceptionator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+from starlette.websockets import WebSocketDisconnect
+
+from corekit.exceptionator.exceptionator import Exceptionator
+from corekit.exceptionator.models import ExceptionContext, ExceptionSource
+
+__all__ = [
+    "ExceptionatorMiddleware",
+    "get_process_exceptionator",
+    "record_http_exception",
+    "set_process_exceptionator",
+    "should_record_http_exception",
+]
+
+ASGIApp = Callable[..., Awaitable[None]]
+
+_process_exceptionator: Exceptionator | None = None
+
+
+def set_process_exceptionator(exceptionator: Exceptionator) -> None:
+    """
+    Remember the process Exceptionator for middleware and HTTP handlers.
+    """
+    global _process_exceptionator
+    _process_exceptionator = exceptionator
+
+
+def get_process_exceptionator() -> Exceptionator:
+    """
+    The Exceptionator installed for this process.
+    """
+    if _process_exceptionator is None:
+        raise RuntimeError("No Exceptionator installed; call set_process_exceptionator first")
+    return _process_exceptionator
+
+
+def should_record_http_exception(exc: BaseException) -> bool:
+    """
+    Client errors and validation failures are not incidents. HTTP 500s are.
+    """
+    if isinstance(exc, RequestValidationError):
+        return False
+    if isinstance(exc, WebSocketDisconnect):
+        return False
+    status = getattr(exc, "status_code", None)
+    if isinstance(exc, HTTPException) and isinstance(status, int) and status < 500:
+        return False
+    return True
+
+
+class ExceptionatorMiddleware:
+    """
+    ASGI middleware that records unhandled HTTP failures and rethrows them.
+
+    Not ``BaseHTTPMiddleware``: that wrapper breaks streaming and exception groups.
+    """
+
+    def __init__(self, app: ASGIApp, exceptionator: Exceptionator | None = None) -> None:
+        self.app = app
+        self._exceptionator = exceptionator
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        try:
+            await self.app(scope, receive, send)
+        except Exception as exc:
+            if should_record_http_exception(exc):
+                self._resolve().capture(
+                    exc,
+                    context=ExceptionContext(
+                        source=ExceptionSource.HTTP,
+                        http_method=scope.get("method"),
+                        http_path=scope.get("path"),
+                    ),
+                )
+            raise
+
+    def _resolve(self) -> Exceptionator:
+        if self._exceptionator is not None:
+            return self._exceptionator
+        return get_process_exceptionator()
+
+
+def record_http_exception(request: Request, exc: HTTPException) -> JSONResponse:
+    """
+    Store HTTP 500s, then return the same JSON body FastAPI would have sent.
+
+    Starlette answers ``HTTPException`` inside the router, so the ASGI middleware
+    never sees it. 4xx responses are returned unchanged and are not incidents.
+    """
+    if should_record_http_exception(exc):
+        get_process_exceptionator().capture(
+            exc,
+            context=ExceptionContext(
+                source=ExceptionSource.HTTP,
+                http_method=request.method,
+                http_path=request.url.path,
+            ),
+        )
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)

python_corekit-0.4.1/corekit/exceptionator/constants.py

@@ -0,0 +1,7 @@
+"""
+Limits shared by every Exceptionator install.
+"""
+
+MESSAGE_MAX_CHARS = 2_000
+TRACEBACK_MAX_CHARS = 32_000
+FINGERPRINT_FRAMES = 8

python_corekit-0.4.1/corekit/exceptionator/exceptionator.py

@@ -0,0 +1,62 @@
+"""
+Catch an exception, run one action, and let the caller rethrow.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from corekit.exceptionator.actions import ExceptionatorAction
+from corekit.exceptionator.guard import (
+    begin_handling,
+    end_handling,
+    handling_active,
+    is_captured,
+    mark_captured,
+)
+from corekit.exceptionator.models import CapturedException, ExceptionContext, build_captured
+from corekit.observability.loggable import Loggable
+
+__all__ = ["Exceptionator"]
+
+
+class Exceptionator(Loggable):
+    """
+    Catch an exception, run the configured action, and let the caller rethrow.
+
+    ``guard`` rethrows. ``capture`` runs the same action and returns, for a
+    caller that has already decided to swallow the error.
+    """
+
+    def __init__(self, action: ExceptionatorAction, *, service: str) -> None:
+        super().__init__()
+        self._action = action
+        self.service = service
+
+    @contextmanager
+    def guard(self, context: ExceptionContext | None = None) -> Iterator[None]:
+        """
+        Run the action when the block raises, then rethrow the original exception.
+        """
+        try:
+            yield
+        except Exception as exc:
+            self.capture(exc, context=context)
+            raise
+
+    def capture(self, exc: BaseException, *, context: ExceptionContext | None = None) -> None:
+        """
+        Run the action once for this exception. Later calls on the same object no-op.
+        """
+        if handling_active() or is_captured(exc):
+            return
+        token = begin_handling()
+        try:
+            captured: CapturedException = build_captured(exc, service=self.service, context=context)
+            mark_captured(exc)
+            self._action.run(captured)
+        except Exception:
+            self.exception("Exceptionator failed while recording an exception")
+        finally:
+            end_handling(token)

python_corekit-0.4.1/corekit/exceptionator/fingerprint.py

@@ -0,0 +1,86 @@
+"""
+Identity for an exception based on its type and innermost frames.
+
+The message is left out so ids embedded in the text do not split one bug into
+many fingerprints.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import traceback
+from types import TracebackType
+from typing import ClassVar
+
+from corekit.exceptionator.constants import FINGERPRINT_FRAMES
+from corekit.utils.text import truncate
+
+__all__ = ["ExceptionFingerprint", "ExceptionText"]
+
+
+class ExceptionText:
+    """
+    Backend text extracted from an exception.
+    """
+
+    @staticmethod
+    def message(exc: BaseException) -> str:
+        """
+        Backend message. Public exceptions stringify to user copy, so prefer ``for_log``.
+        """
+        for_log = getattr(exc, "for_log", None)
+        if callable(for_log):
+            try:
+                return str(for_log())
+            except Exception:
+                return str(exc)
+        return str(exc)
+
+    @staticmethod
+    def first_line(text: str, limit: int) -> str:
+        """
+        The first line of ``text``, truncated to ``limit`` characters.
+        """
+        line = text.splitlines()[0] if text else ""
+        return truncate(line, limit)
+
+
+class ExceptionFingerprint:
+    """
+    Stable identity for an exception based on its type and innermost frames.
+    """
+
+    path_markers: ClassVar[tuple[str, ...]] = ()
+
+    def of(self, exc: BaseException) -> str:
+        """
+        Hash the exception type plus the innermost stack frames.
+        """
+        frames = traceback.extract_tb(exc.__traceback__)[-FINGERPRINT_FRAMES:]
+        parts = [type(exc).__qualname__]
+        for frame in frames:
+            parts.append(f"{self.normalize_path(frame.filename)}|{frame.name}|{frame.lineno}")
+        return hashlib.sha256("\n".join(parts).encode()).hexdigest()
+
+    @classmethod
+    def normalize_path(cls, filename: str) -> str:
+        """
+        Drop machine-specific prefixes so a container path and a checkout match.
+        """
+        normalized = filename.replace("\\", "/")
+        for marker in cls.path_markers:
+            index = normalized.find(marker)
+            if index >= 0:
+                return normalized[index:]
+        parts = [part for part in normalized.split("/") if part]
+        if not parts:
+            return normalized
+        return "/".join(parts[-2:])
+
+    @staticmethod
+    def format_traceback(exc: BaseException) -> str:
+        """
+        Render the traceback text for storage.
+        """
+        tb: TracebackType | None = exc.__traceback__
+        return "".join(traceback.format_exception(type(exc), exc, tb))

python_corekit-0.4.1/corekit/exceptionator/guard.py

@@ -0,0 +1,53 @@
+"""
+ContextVar and per-exception marker so one failure is recorded once.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+__all__ = [
+    "begin_handling",
+    "end_handling",
+    "handling_active",
+    "is_captured",
+    "mark_captured",
+]
+
+CAPTURED_MARKER = "_exceptionator_captured"
+_handling: ContextVar[bool] = ContextVar("exceptionator_handling", default=False)
+
+
+def is_captured(exc: BaseException) -> bool:
+    """
+    Whether this exception object was already handed to an Exceptionator.
+    """
+    return bool(getattr(exc, CAPTURED_MARKER, False))
+
+
+def mark_captured(exc: BaseException) -> None:
+    """
+    Remember that this exception object has been handled.
+    """
+    setattr(exc, CAPTURED_MARKER, True)
+
+
+def handling_active() -> bool:
+    """
+    Whether this task is already inside the Exceptionator.
+    """
+    return _handling.get()
+
+
+def begin_handling() -> Token[bool]:
+    """
+    Mark this task as inside the Exceptionator. Pair with ``end_handling``.
+    """
+    return _handling.set(True)
+
+
+def end_handling(token: Token[bool]) -> None:
+    """
+    Leave the Exceptionator guard.
+    """
+    _handling.reset(token)

python_corekit-0.4.1/corekit/exceptionator/jobs.py

@@ -0,0 +1,52 @@
+"""
+Hook ``run_task`` calls after a task fails and before ``failure()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from corekit.exceptionator.models import ExceptionContext, ExceptionSource
+
+if TYPE_CHECKING:
+    from corekit.exceptionator.exceptionator import Exceptionator
+
+__all__ = ["clear_run_task_hook", "get_run_task_hook", "install_run_task_hook"]
+
+RunTaskHook = Callable[[str, BaseException], None]
+
+_hook: RunTaskHook | None = None
+
+
+def install_run_task_hook(exceptionator: Exceptionator) -> None:
+    """
+    Register ``exceptionator`` so ``run_task`` captures failures with the task name.
+
+    Passing the same instance again is a no-op. Call ``clear_run_task_hook`` to
+    remove it. With no hook registered, ``run_task`` behaves as it did before.
+    """
+    global _hook
+
+    def hook(task_name: str, exc: BaseException) -> None:
+        exceptionator.capture(
+            exc,
+            context=ExceptionContext(source=ExceptionSource.RQ, job_name=task_name),
+        )
+
+    _hook = hook
+
+
+def clear_run_task_hook() -> None:
+    """
+    Remove any ``run_task`` capture hook.
+    """
+    global _hook
+    _hook = None
+
+
+def get_run_task_hook() -> RunTaskHook | None:
+    """
+    The hook ``run_task`` should call, or ``None``.
+    """
+    return _hook