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

{python_corekit-0.2.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.2.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.2.0
+python-corekit~=0.4.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -281,10 +283,36 @@ 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
-from corekit.http.client import BaseApiClient
+from corekit.http import BaseApiClient
 
 class GithubClient(BaseApiClient):
     """
@@ -301,7 +329,8 @@ response.data["login"]
 
 Retries 429 and 5xx with exponential backoff. Every response is a
 `BaseApiResponse`, so a non-JSON error page leaves `data` empty rather than
-raising. `async_get`, `async_post` and friends do the same without blocking.
+raising. The same methods are awaitable inside a running event loop:
+`await client.get(...)`.
 
 ## Serialization
 
@@ -351,7 +380,7 @@ Settings are grouped by concern, so `get_settings().concurrency.max_threads`
 says where a value belongs. Environment variables use a double underscore for
 the section: `COREKIT_CONCURRENCY__MAX_THREADS=16`.
 
-Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO_SALT`). Empty
+Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO__SALT`). Empty
 values are treated as unset, because container runtimes routinely pass `FOO=`
 for a variable that was never set.
 
@@ -375,7 +404,6 @@ Imports go downward only.
 ```
 corekit/
   config/                          settings, sources, loader
-  constants.py
 
   exceptions/                      error types
 
@@ -390,10 +418,11 @@ corekit/
   connections/                     the Connectable lifecycle and @connect
     sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
-  http/                            BaseApiClient, retries, responses
+  http/                            BaseHttpClient, BaseApiClient, retries, responses
 
   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.2.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.2.0
+python-corekit~=0.4.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -246,10 +247,36 @@ 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
-from corekit.http.client import BaseApiClient
+from corekit.http import BaseApiClient
 
 class GithubClient(BaseApiClient):
     """
@@ -266,7 +293,8 @@ response.data["login"]
 
 Retries 429 and 5xx with exponential backoff. Every response is a
 `BaseApiResponse`, so a non-JSON error page leaves `data` empty rather than
-raising. `async_get`, `async_post` and friends do the same without blocking.
+raising. The same methods are awaitable inside a running event loop:
+`await client.get(...)`.
 
 ## Serialization
 
@@ -316,7 +344,7 @@ Settings are grouped by concern, so `get_settings().concurrency.max_threads`
 says where a value belongs. Environment variables use a double underscore for
 the section: `COREKIT_CONCURRENCY__MAX_THREADS=16`.
 
-Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO_SALT`). Empty
+Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO__SALT`). Empty
 values are treated as unset, because container runtimes routinely pass `FOO=`
 for a variable that was never set.
 
@@ -340,7 +368,6 @@ Imports go downward only.
 ```
 corekit/
   config/                          settings, sources, loader
-  constants.py
 
   exceptions/                      error types
 
@@ -355,10 +382,11 @@ corekit/
   connections/                     the Connectable lifecycle and @connect
     sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
-  http/                            BaseApiClient, retries, responses
+  http/                            BaseHttpClient, BaseApiClient, retries, responses
 
   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.2.0 → python_corekit-0.4.0}/corekit/api/application.py

@@ -26,16 +26,34 @@ from typing import Any, Sequence
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from corekit.api.middleware import MiddlewareStack
 from corekit.api.routers import CatchAllRouter, SimpleRouter, router_registry
+from corekit.exceptions import CoreHTTPException
 from corekit.observability.loggable import Loggable
 
 __all__ = ["Application"]
 
 
+def _origin_in_package(router: SimpleRouter, package_name: str) -> bool:
+    """
+    Whether this router was constructed by ``package_name`` or a submodule.
+    """
+    origin = router._origin_module
+    return origin == package_name or origin.startswith(f"{package_name}.")
+
+
+async def _core_http_exception_handler(request: Any, exc: CoreHTTPException) -> JSONResponse:
+    """
+    The same body FastAPI returns for ``HTTPException``.
+    """
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)
+
+
 class Application(FastAPI, Loggable):
     """
     ``FastAPI`` plus router discovery, middleware helpers and static mounting.
@@ -47,6 +65,7 @@ class Application(FastAPI, Loggable):
         """
         FastAPI.__init__(self, *args, **kwargs)
         Loggable.__init__(self)
+        self._register_http_exception_handler()
 
     # ─── Routers ──────────────────────────────────────────────────────────
 
@@ -55,9 +74,12 @@ class Application(FastAPI, Loggable):
         Import every module under ``package`` and mount the routers it defines.
 
         Importing a module is what constructs its routers, so discovery is a
-        walk over ``package`` that lets each one register itself. A router that
-        was included into another router during that walk is skipped -- its
-        parent already owns it -- and any ``CatchAllRouter`` is mounted last.
+        walk over ``package`` that lets each one register itself. Only routers
+        constructed inside that package are mounted: the registry is
+        process-wide, and an unclaimed router from some other import must not
+        ride along. A router that was included into another router is skipped
+        -- its parent already owns it -- and any ``CatchAllRouter`` is mounted
+        last.
 
         Args:
             package: The imported package to search, e.g. ``app.backend.routers``.
@@ -78,11 +100,12 @@ class Application(FastAPI, Loggable):
 
         self._warn_on_unimportable_dirs(package)
 
-        before = len(router_registry)
         scanned = self._import_submodules(package)
-        discovered = len(router_registry) - before
-
-        mountable = router_registry.unclaimed
+        # unclaimed is every top-level router in the process. Mounting that
+        # list would include routers built by some other package that happens
+        # to be imported. Origin is where the instance was constructed, which
+        # is the scanned package for a router that belongs here.
+        mountable = [router for router in router_registry.unclaimed if _origin_in_package(router, name)]
         if not mountable:
             raise ValueError(
                 f"No routers found in '{name}' (scanned {scanned} modules). "
@@ -90,8 +113,9 @@ class Application(FastAPI, Loggable):
                 f"a SimpleRouter or SmartRouter at import time."
             )
 
-        claimed = discovered - len(mountable)
-        self.info(f"  scanned {scanned} modules, found {discovered} routers")
+        in_package = [router for router in router_registry if _origin_in_package(router, name)]
+        claimed = len(in_package) - len(mountable)
+        self.info(f"  scanned {scanned} modules, found {len(in_package)} routers")
         if claimed > 0:
             plural = "s" if claimed != 1 else ""
             self.info(f"  skipped {claimed} sub-router{plural} (already included by a parent)")
@@ -235,3 +259,17 @@ class Application(FastAPI, Loggable):
         self.mount(url_path, StaticFiles(directory=str(path), **kwargs), name=name or url_path.strip("/"))
         self.info(f"  + static {url_path:<24} -> {path}")
         return True
+
+    def _register_http_exception_handler(self) -> None:
+        """
+        Handle the library's HTTP exceptions the same way FastAPI handles its own.
+
+        ``CoreHTTPException`` is already an ``HTTPException``, so Starlette
+        would answer it. Registering the type explicitly keeps that response
+        -- ``{"detail": ...}`` only, never ``message`` or ``error`` -- even
+        if a later change in lookup order would otherwise miss the subclass.
+        A handler the caller already installed is left in place.
+        """
+        if CoreHTTPException in self.exception_handlers:
+            return
+        self.add_exception_handler(CoreHTTPException, _core_http_exception_handler)

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/api/lifespan.py

@@ -108,7 +108,9 @@ class Lifespan(Loggable):
             startup: Called on the way up, in the order steps were added.
             shutdown: Called on the way down, in reverse order. Called only if
                 ``startup`` completed, so it can assume what ``startup`` builds.
-            tags: Free-form labels, for callers that group or filter steps.
+            tags: Labels used by ``for_tags``. Untagged steps always run; a
+                tagged step runs only when one of its tags is selected. With
+                no filter, every step runs.
             always_shutdown: Call ``shutdown`` even when ``startup`` raised.
                 For a startup that acquires something before it can fail -- a
                 connection opened, then a handshake that throws. The hook then
@@ -136,6 +138,25 @@ class Lifespan(Loggable):
         """The registered steps, in the order they will start."""
         return list(self._steps)
 
+    def for_tags(self, *tags: str) -> "Lifespan":
+        """
+        A lifespan that runs the steps matching ``tags``, plus untagged ones.
+
+        An untagged step is ordinary startup and always runs. A tagged step
+        runs only when the caller asked for one of its tags, so a label is a
+        filter rather than decoration. No tags means every step, which is
+        what ``__call__`` does.
+        """
+        if not tags:
+            return self
+
+        wanted = set(tags)
+        selected = Lifespan()
+        for step in self._steps:
+            if not step.tags or wanted.intersection(step.tags):
+                selected._steps.append(step)
+        return selected
+
     @asynccontextmanager
     async def __call__(self, app: Any = None) -> AsyncIterator[None]:
         """
@@ -166,7 +187,8 @@ class Lifespan(Loggable):
         stack.push_async_callback(self._run_shutdown, step)
 
         if step.startup is not None:
-            self.info(f"  ^ {step.name}")
+            label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+            self.info(f"  ^ {label}")
             try:
                 await self._maybe_await(step.startup)
             except Exception:
@@ -192,7 +214,8 @@ class Lifespan(Loggable):
                 self.warning(f"  - {step.name} (skipped: startup did not complete)")
             return
 
-        self.info(f"  v {step.name}")
+        label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+        self.info(f"  v {label}")
         try:
             await self._maybe_await(step.shutdown)
         except Exception:

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/concurrency/__init__.py

@@ -2,8 +2,8 @@
 Concurrency primitives: per-thread storage, workers, and parallel mapping.
 """
 
-from corekit.concurrency.decorators import parallelize
+from corekit.concurrency.decorators import allow_sync, parallelize
 from corekit.concurrency.thread_local import ThreadLocalRegistry
 from corekit.concurrency.worker import ThreadWorker
 
-__all__ = ["ThreadLocalRegistry", "ThreadWorker", "parallelize"]
+__all__ = ["ThreadLocalRegistry", "ThreadWorker", "allow_sync", "parallelize"]

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/concurrency/decorators.py

@@ -18,19 +18,26 @@ machine rather than an error message.
 
 Results arrive out of order, because they arrive as they complete. Pass
 ``ordered=True`` to get them in the order the inputs were given.
+
+``allow_sync`` wraps an async function so a script can call it directly, while
+an already-running event loop still gets a coroutine to await.
 """
 
+import asyncio
 import functools
+import logging
+from collections.abc import Awaitable, Callable
 from concurrent.futures import Future, ThreadPoolExecutor, as_completed
-from typing import Any, Callable, Iterable, Iterator
+from typing import Any, Iterable, Iterator, ParamSpec, TypeVar
 
 from corekit.config import get_settings
-from corekit.observability import Loggable
 
-__all__ = ["parallelize"]
+__all__ = ["parallelize", "allow_sync"]
+
+_logger = logging.getLogger("parallelize")
 
-_logger = Loggable()
-_logger.logger = _logger.logger.getChild("parallelize")
+P = ParamSpec("P")
+R = TypeVar("R")
 
 
 def parallelize(
@@ -70,3 +77,23 @@ def parallelize(
         return wrapper
 
     return decorator
+
+
+def allow_sync(async_func: Callable[P, Awaitable[R]]) -> Callable[P, R | Awaitable[R]]:
+    """
+    Call an async function from sync code, or return its coroutine if a loop is running.
+
+    A script gets the result back immediately. Inside an async app the wrapper
+    returns the coroutine, so the caller must await it — calling the wrapper
+    and ignoring the result will not run the function.
+    """
+
+    @functools.wraps(async_func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | Awaitable[R]:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(async_func(*args, **kwargs))
+        return async_func(*args, **kwargs)
+
+    return wrapper

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/concurrency/thread_local.py

@@ -19,7 +19,7 @@ import threading
 from typing import Any
 
 from corekit.observability.loggable import Loggable
-from corekit.registry import SmartRegistry
+from corekit.registry import normalize_key
 
 __all__ = ["ThreadLocalRegistry"]
 
@@ -59,7 +59,7 @@ class ThreadLocalRegistry(threading.local, Loggable):
         turn SQLConnection into "sqlconnection" rather than "sql_connection".
         """
         name = key.__name__ if isinstance(key, type) else str(key)
-        return SmartRegistry.__normalize_key__(name).replace("-", "_")
+        return normalize_key(name).replace("-", "_")
 
     def get(self, key: Any, fallback: Any = None) -> Any:
         """

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/concurrency/worker.py

@@ -5,6 +5,15 @@ import time
 
 
 class ThreadWorker(threading.Thread):
+    """
+    A daemon thread that waits for ``can_start``, then calls ``process`` once.
+
+    ``timeout`` and ``loop`` are stored for a subclass that wants them.
+    ``run`` does not enforce ``timeout`` and does not drive ``loop``.
+    ``stop`` sets ``running`` so a subclass of ``process`` can notice it; it
+    does not interrupt a thread already inside ``process``.
+    """
+
     def __init__(
         self,
         can_start: threading.Event,

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/config/loader.py

@@ -9,6 +9,8 @@ settings know only their own shape.
 from pathlib import Path
 from typing import Any
 
+from pydantic import ValidationError
+
 from corekit.config.settings import ENV_PREFIX, CorekitSettings
 from corekit.config.sources import ConfigFileSource, ConfigSource, EnvironmentSource, PyprojectSource
 from corekit.observability import Loggable
@@ -72,11 +74,12 @@ class SettingsLoader(Loggable):
         """
         Read every source and construct the settings.
 
-        Invalid configuration falls back to defaults rather than raising:
-        corekit has to remain importable, and a library that refuses to load
-        because of a stray value in a file is worse than one that logs the
-        problem and carries on. The log line is the difference between this and
-        silently ignoring it.
+        Invalid configuration drops the bad section and keeps the rest.
+        A bad thread count must not discard a valid salt or serialization
+        key that arrived from another section or the environment. If what
+        remains still will not validate, the last resort is defaults --
+        corekit has to remain importable. The log line is the difference
+        between this and silently ignoring it.
         """
         values: dict[str, Any] = {}
         for source in self.sources():
@@ -84,10 +87,44 @@ class SettingsLoader(Loggable):
 
         try:
             return CorekitSettings(**values)
+        except ValidationError as exc:
+            cleaned, dropped = self._without_invalid_sections(values, exc)
+            if dropped:
+                self.error(
+                    f"Invalid corekit configuration in {', '.join(dropped)}; "
+                    f"those sections fall back to defaults: {exc}"
+                )
+                try:
+                    return CorekitSettings(**cleaned)
+                except ValidationError as retry_exc:
+                    self.error(f"Invalid corekit configuration, falling back to defaults: {retry_exc}")
+                    return CorekitSettings()
+            self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
+            return CorekitSettings()
         except Exception as exc:
             self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
             return CorekitSettings()
 
+    @staticmethod
+    def _without_invalid_sections(values: dict[str, Any], exc: ValidationError) -> tuple[dict[str, Any], list[str]]:
+        """
+        Drop each section named in a validation error, leaving the others.
+
+        A section is the first element of the error location. A failure that
+        names no section cannot be isolated, so nothing is dropped and the
+        caller falls back to defaults.
+        """
+        dropped: list[str] = []
+        for error in exc.errors():
+            loc = error.get("loc") or ()
+            if not loc:
+                continue
+            section = str(loc[0])
+            if section not in dropped:
+                dropped.append(section)
+        cleaned = {key: value for key, value in values.items() if key not in dropped}
+        return cleaned, dropped
+
     @staticmethod
     def _merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
         """

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/config/settings.py

@@ -35,6 +35,10 @@ class StandardsSettings(BaseModel):
 
     Off by default. These are conventions, not library invariants, and crashing
     a consumer's application over a missing docstring would be hostile.
+
+    ``strict_mode`` makes a ``SmartRegistry`` refuse a second write to a
+    normalized key instead of warning and replacing. It does not imply
+    ``require_handler_docstrings``; that check stays its own flag.
     """
 
     require_handler_docstrings: bool = False
@@ -80,7 +84,13 @@ class ConcurrencySettings(BaseModel):
     @staticmethod
     def cpu_default() -> int:
         """
-        A reasonable thread count for this machine, for callers that want one.
+        A machine-sized thread count, for a caller that asks for one.
+
+        Not what ``resolve`` or ``parallelize`` use when the caller is silent.
+        Those use ``default_threads``. Pass this in when the work should
+        scale with the machine::
+
+            parallelize(num_threads=ConcurrencySettings.cpu_default())
         """
         return min(32, (os.cpu_count() or 1) * 5)
 

{python_corekit-0.2.0 → python_corekit-0.4.0}/corekit/connections/__init__.py

@@ -17,7 +17,12 @@ implementations of the abstraction directly above them, and there is no useful
 way to think about one without the other.
 """
 
-from corekit.connections.connectable import Connectable, ConnectableType, ConnectionPreference
+from corekit.connections.connectable import (
+    Connectable,
+    ConnectableType,
+    ConnectionPreference,
+    ReadOnlyConnectionError,
+)
 from corekit.connections.decorators import connect
 from corekit.connections.registry import ConnectionRegistry, registry
 
@@ -26,6 +31,7 @@ __all__ = [
     "ConnectableType",
     "ConnectionPreference",
     "ConnectionRegistry",
+    "ReadOnlyConnectionError",
     "connect",
     "registry",
 ]