msgflux 0.3.0__tar.gz → 0.5.0__tar.gz

{msgflux-0.3.0 → msgflux-0.5.0}/.pre-commit-config.yaml

@@ -7,12 +7,12 @@ repos:
       - id: gitleaks
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.7 # uv version.
+    rev: 0.11.16 # uv version.
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.11
+    rev: v0.15.14
     hooks:
       - id: ruff
         args: [--fix]

msgflux-0.5.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## [0.5.0] - 2026-05-29
+
+### Feat
+- Added opt-in input validation for signatures (#82).
+- Added method hooks beyond `forward` (#87).
+- Added `extra_body` passthrough extensions for OpenAI-compatible chat completions (#88).
+- Added Open-Meteo weather retriever support and the builtin `Weather` tool (#97).
+- Added tool display names and usage guidance metadata (#98).
+- Added the Ceramic web retriever (#99).
+- Added the SearXNG web retriever (#101).
+- Added agent prompt warmup (#105).
+- Added `msgspec.Struct` tool parameter support (#110).
+- Added Agent Skills runtime support (#111).
+
+### Docs
+- Corrected retriever section numbering in `docs/learn/nn/agent/tools.md` (#80).
+- Added the Builtin Tools section to `tools.md` (#81).
+
+### Refactor
+- Renamed the WebSearch steering parameter to `goal` (#100).
+- Clarified tool display-name and usage-guidance examples and aligned `ToolLibrary.get_tool_display_names()` with a fallback to the registered tool name (#114).
+
+### CI / Maintenance
+- Updated pre-commit hooks (#86).
+- Bumped `packaging` from 25.0 to 26.2 (#92).
+- Bumped `openai` from 2.32.0 to 2.38.0 (#106).
+- Bumped `bm25s` from 0.3.4 to 0.3.9 (#107).
+- Bumped `ruff` from 0.15.11 to 0.15.14 (#108).
+- Bumped `pymdown-extensions` from 10.21.2 to 10.21.3 (#109).
+- Bumped `pytest-asyncio` from 1.3.0 to 1.4.0 (#113).
+
+## [0.4.1] - 2026-04-22
+
+- Fixes: restored uv.lock file for CI compatibility (#78).
+
+## [0.4.0] - 2026-04-22
+
+- Features: added new web retrievers (Arxiv, Brave, Exa, LinkUp, SerpAPI, Tavily) and model integrations (Brave, Exa), plus configurable WebSearch tool (#71).
+- Web Retriever: added support for Wikipedia highlighting in web retriever section (#73).
+- Providers: added OpenAI-compatible `extra_body` support for chat completions (#72).
+- Maintenance: removed uv.lock file (#74).
+
+## [0.3.0] - 2026-04-20
+
+- Features: added OpenAI prompt cache retention support (#52), token logprobs metadata for chat completions (#53), and the `LLMAsVerifier` workflow with docs and examples (#54).
+- Fixes: mapped OpenRouter `reasoning_max_tokens` to `extra_body.reasoning.max_tokens` and enforced the `reasoning_effort` conflict rule (#57).
+- Docs: updated chat completion and agent reasoning docs to reflect the OpenRouter-only reasoning budget behavior (#56, #57).
+- Maintenance: updated pre-commit hooks (#55).
+
+## [0.2.0] - 2026-04-17
+
+- Features: added `provider/model-id` string shorthand support to `Agent`, `Speaker`, and `Transcriber` (#26, #27, #28), plus runtime tool controls for `Agent` (#30).
+- Fixes: fixed registry naming for generic callables (#29).
+- Maintenance: updated release automation and cleaned up the release script (#36, #49).
+
+## [0.1.1] - 2026-04-15
+
+- Fixed message copying in the OpenAI provider (#47).
+- Fixed isolation of injected messages for agent tools (#46).
+- Updated CI and dependency tooling to keep release checks passing (#45, #44, #38, #37, #35, #34, #33, #32).
+
+## [0.1.0] - 2026-04-09
+
+## [0.1.0a31] - 2026-04-09

{msgflux-0.3.0 → msgflux-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msgflux
-Version: 0.3.0
+Version: 0.5.0
 Summary: Messages and Dynamic AI Systems in Python powered by pretrained models
 Project-URL: Homepage, https://github.com/msgflux/msgflux
 Project-URL: Documentation, https://github.com/msgflux/msgflux
@@ -26,6 +26,7 @@ Requires-Python: >=3.10
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: msgspec-ext>=0.5.1
 Requires-Dist: msgtrace-sdk>=1.1.0
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: tenacity>=8.2.3
 Requires-Dist: typing-extensions>=4.14.1
 Requires-Dist: uvloop>=0.21.0; sys_platform != 'win32'

{msgflux-0.3.0 → msgflux-0.5.0}/docs/dependency-management.md

@@ -10,16 +10,17 @@ hide:
 
 ### Chat Completion
 
-| Provider    | Dependency        | Auth Env             |
-|-------------|-------------------|----------------------|
-| Cerebras    | `msgflux[openai]` | `CEREBRAS_API_KEY`   |
-| Groq        | `msgflux[openai]` | `GROQ_API_KEY`       |
-| Ollama      | `msgflux[openai]` |                      |
-| OpenAI      | `msgflux[openai]` | `OPENAI_API_KEY`     |
-| OpenRouter  | `msgflux[openai]` | `OPENROUTER_API_KEY` |
-| SambaNova   | `msgflux[openai]` | `SAMBANOVA_API_KEY`  |
-| Together    | `msgflux[openai]` | `TOGETHER_API_KEY`   |
-| vLLM        | `msgflux[openai]` |                      |
+| Provider    | Dependency        | Auth Env               |
+|-------------|-------------------|------------------------|
+| Brave       | `msgflux[openai]` | `BRAVE_SEARCH_API_KEY` |
+| Cerebras    | `msgflux[openai]` | `CEREBRAS_API_KEY`     |
+| Groq        | `msgflux[openai]` | `GROQ_API_KEY`         |
+| Ollama      | `msgflux[openai]` |                        |
+| OpenAI      | `msgflux[openai]` | `OPENAI_API_KEY`       |
+| OpenRouter  | `msgflux[openai]` | `OPENROUTER_API_KEY`   |
+| SambaNova   | `msgflux[openai]` | `SAMBANOVA_API_KEY`    |
+| Together    | `msgflux[openai]` | `TOGETHER_API_KEY`     |
+| vLLM        | `msgflux[openai]` |                        |
 
 ### Image Embedder
 
@@ -144,6 +145,15 @@ hide:
 
 ### Web Search
 
-| Provider    | Dependency    |
-|-------------|---------------|
-| Wikipedia   | `wikipedia`   |
+| Provider    | Installation                     | Auth Env                         |
+|-------------|----------------------------------|-----------------------------------|
+| Trafilatura | `httpx`, `trafilatura`           |                                   |
+| SearXNG     | `httpx`                          |                                   |
+| SerpApi     | `httpx`                          | `SERPAPI_KEY`                     |
+| Ceramic     | `httpx`                          | `CERAMIC_API_KEY`                 |
+| Linkup      | `linkup-sdk`                     | `LINKUP_API_KEY`                  |
+| Tavily      | `tavily-python`                  | `TAVILY_API_KEY`                  |
+| Exa         | `exa-py`                         | `EXA_API_KEY`                     |
+| Brave       | `brave-search-python-client`     | `BRAVE_SEARCH_API_KEY`            |
+| arXiv       | `arxiv`                          |                                   |
+| Wikipedia   | `wikipedia`                      |                                   |

{msgflux-0.3.0 → msgflux-0.5.0}/docs/index.md

@@ -34,6 +34,8 @@ hide:
 
 msgFlux is an open-source framework for building dynamic AI systems with **composable modules**. It treats prompts, signatures, tools, and message flow as explicit program structure instead of ad-hoc glue. Architecture, data flow, and prompting remain separate layers, so systems can evolve by changing contracts, modules, or routes without forcing everything to change together.
 
+For web search, msgFlux includes both retriever-backed and model-backed options. The built-in `WebSearch` tool can be pointed at a retriever backend like `retriever/wikipedia` or a model backend like `model/openai/gpt-4o-search-preview`, returns `data` plus `annotations` when the backend supplies citations, and can read its engine plus JSON params from `MSGFLUX_TOOL_WEB_SEARCH_*` environment variables.
+
 ## **AI Systems *not* ML Systems**
 
 **ML systems** are systems *for* AI - they train, evaluate, and deploy models. **AI systems** are systems *with* AI - software where pretrained models operate as components inside a broader application. In that setting, the model is not the whole product; it is one building block among many. You are not optimizing weights - you are designing behavior, interfaces, and flow around a model. This is the space msgFlux occupies.

{msgflux-0.3.0 → msgflux-0.5.0}/docs/learn/models/chat_completion.md

@@ -72,6 +72,7 @@ Chat completion models are stateless - they don't maintain conversation history
         verbose=False,                 # Print raw output before transformation
         # --- Search ---
         web_search_options={},         # Web search config (OpenAI / OpenRouter only)
+        extra_body={},                 # Provider-specific OpenAI-compatible extensions
         prompt_cache_retention="24h",  # OpenAI only: "in_memory" or "24h"
         # --- Infrastructure ---
         base_url="https://api.openai.com/v1",  # Override provider API endpoint
@@ -82,6 +83,32 @@ Chat completion models are stateless - they don't maintain conversation history
     )
     ```
 
+Use `extra_body` for provider-specific request body fields supported by
+OpenAI-compatible APIs but not modeled directly by msgFlux. The dict is
+forwarded to the underlying OpenAI SDK client.
+
+You can also pass provider-specific fields directly as keyword arguments
+in the model constructor, or per request with `model(...)` / `model.acall(...)`.
+msgFlux merges these kwargs into `extra_body`.
+
+```python
+import msgflux as mf
+
+model = mf.Model.chat_completion(
+    "brave/brave",
+    extra_body={"enable_citations": True},
+    enable_entities=True,    # merged into extra_body
+    enable_research=False,   # merged into extra_body
+)
+
+# Per-request extensions are merged with constructor defaults.
+response = model(
+    "Search the latest release notes.",
+    extra_body={"country": "US"},
+    enable_citations=True,
+)
+```
+
 ## 2. **System Prompt**
 
 The `system_prompt` parameter sets the model's overarching behavior and role before any user messages. It is a convenience shorthand: when provided, msgFlux automatically inserts a `system` message at the beginning of the conversation, so you don't have to do it manually in the messages list.
@@ -217,6 +244,23 @@ The cache is sensitive to:
 
 Changing any of these creates a new cache entry.
 
+### 3.2 **Prompt Cache Warmup**
+
+Some providers cache long prompt prefixes server-side. For agent-level warmup, use `Agent.warmup_system_prompt()`. It sends the rendered system prompt and tool schemas without task messages, chat history, or checkpointer state.
+
+See [Agent — Prompt Cache Warmup](../nn/agent/prompt-cache.md) for the recommended usage.
+
+OpenAI-compatible chat providers use `warmup_max_tokens=1` by default:
+
+```python
+model = mf.Model.chat_completion(
+    "openai/gpt-4.1-mini",
+    warmup_max_tokens=1,
+)
+```
+
+This is separate from `enable_cache`: response caching is local/in-process, while prompt cache warmup targets the provider's prompt cache.
+
 ## 4. **Message Formats**
 
 ???+ example
@@ -736,6 +780,8 @@ Force the model to start its response with specific text. msgFlux appends the va
 
 The `web_search_options` parameter enables real-time web search, letting the model ground its answers in up-to-date information retrieved from the internet. It is currently supported by OpenAI search models (`gpt-4o-search-preview`, `gpt-4o-mini-search-preview`) and OpenRouter.
 
+OpenAI-compatible search providers can also expose chat completion models that search the web before answering. Brave uses `BRAVE_SEARCH_API_KEY` with the `brave/brave` model id, and Exa uses `EXA_API_KEY` with the `exa/exa` model id.
+
 !!! info "Dependencies"
     Install the OpenAI extra if you haven't already:
 
@@ -794,6 +840,92 @@ The `web_search_options` parameter enables real-time web search, letting the mod
         print(response.consume())
         ```
 
+    === "Brave Search"
+
+        Brave Answers uses an OpenAI-compatible endpoint. Set
+        `BRAVE_SEARCH_API_KEY` and use the `brave/brave` model id:
+
+        ```python
+        import msgflux as mf
+
+        mf.set_envs(BRAVE_SEARCH_API_KEY="...")
+
+        model = mf.Model.chat_completion("brave/brave")
+        response = model("What are the latest Python packaging updates?")
+
+        print(response.consume())
+        ```
+
+        Brave-specific request fields are passed through `extra_body`:
+
+        ```python
+        import msgflux as mf
+
+        mf.set_envs(BRAVE_SEARCH_API_KEY="...")
+
+        model = mf.Model.chat_completion(
+            "brave/brave",
+            extra_body={
+                "country": "BR",   # target country for search results
+                "language": "pt",  # answer language
+            },
+        )
+
+        response = model("Quais foram as principais novidades do Python este mês?")
+        print(response.consume())
+        ```
+
+        Brave's richer answer fields require streaming mode:
+
+        ```python
+        import msgflux as mf
+
+        mf.set_envs(BRAVE_SEARCH_API_KEY="...")
+
+        model = mf.Model.chat_completion(
+            "brave/brave",
+            extra_body={
+                "country": "US",
+                "language": "en",
+                "enable_citations": True,
+                "enable_entities": True,
+                "enable_research": False,
+            },
+        )
+
+        response = model("Summarize the latest Python packaging updates.", stream=True)
+
+        async for chunk in response.consume():
+            print(chunk, end="", flush=True)
+        ```
+
+        Supported Brave Answers parameters include:
+
+        | Parameter | Description | Default |
+        |---|---|---|
+        | `country` | Target country for search results | `"us"` |
+        | `language` | Response language | `"en"` |
+        | `enable_citations` | Include inline citation tags in streamed responses | `False` |
+        | `enable_entities` | Include entity tags in streamed responses | `False` |
+        | `enable_research` | Enable multi-search research mode for more thorough answers | `False` |
+
+        `enable_citations`, `enable_entities`, and `enable_research` require
+        `stream=True`. Research mode can be slower and more expensive because
+        Brave may run multiple searches before answering.
+
+    === "Exa Answer"
+
+        ```python
+        import msgflux as mf
+
+        mf.set_envs(EXA_API_KEY="...")
+
+        model = mf.Model.chat_completion("exa/exa")
+        response = model("What are the latest changes in Python packaging?")
+
+        print(response.consume())
+        ```
+
 ### 11.1 **search_context_size**
 
 Controls how much web content is retrieved and included in the model's context window:

{msgflux-0.3.0 → msgflux-0.5.0}/docs/learn/nn/agent/hooks.md

@@ -1,19 +1,21 @@
 # Hooks & Guards
 
-Hooks are the primary mechanism for intercepting and validating data flowing through Modules. The `Hook` base class provides the interface, and `Guard` is a built-in hook for input/output validation.
+Hooks are the primary mechanism for intercepting and validating data flowing through Modules. The `Hook` base class provides the interface, and `Guard` is a built-in hook for input/output validation. Hooks can target either the module execution boundary (`forward`) or a specific method on the module.
 
 ## Guard
 
 A `Guard` validates inputs and/or outputs of a Module. Each Guard wraps a **validator** callable and defines:
 
-- **`on`** — when to run: `"pre"` (before forward) or `"post"` (after forward).
+- **`on`** — when to run: `"pre"` (before execution) or `"post"` (after execution).
 - **`message`** — controls the reaction when `safe=False`:
     - **With `message`** — short-circuits the pipeline and returns the message as the response (the model is never called).
     - **Without `message`** (default) — raises `UnsafeUserInputError` (pre) or `UnsafeModelResponseError` (post).
-- **`target`** — submodule to register on. Defaults to `"generator"`.
+- **`target`** — submodule to register on. Defaults to `"generator"` for forward hooks and `None` for method hooks.
+- **`method`** — optional method name. When omitted, the guard runs around `forward`. When set, it runs around that method instead.
 - **`include_data`** — if `True`, attaches the data that triggered the guard to the raised exception via `exc.data`. Defaults to `False` for security (the data may contain unsafe content).
 
 The validator receives `data` as a positional argument and must return either a dict with `"safe"` (bool) or a `ModelResponse` (auto-consumed by Guard).
+For `Guard(..., on="pre", method=...)`, `data` is the method `kwargs` payload. If a method is intended to be guarded in pre-mode, prefer a keyword-oriented signature.
 
 ```python
 from msgflux.nn.hooks import Guard
@@ -27,8 +29,26 @@ guard = Guard(validator=my_validator, on="pre", message="Not allowed.")
 
 # Raises exception when safe=False
 guard = Guard(validator=my_validator, on="pre")
+
+# Guard a specific method on the module itself
+guard = Guard(validator=my_validator, on="post", method="_prepare_response")
 ```
 
+!!! note "Method Guard Input Shape"
+    `Guard` on a specific method is best suited for keyword-oriented extension points.
+    In `on="pre"` mode, the validator sees the method `kwargs`, not positional args.
+
+    ```python
+    class MyModule(nn.Module):
+        def forward(self, text):
+            return self.validate(data=text)
+
+        def validate(self, *, data):
+            return data
+
+    guard = Guard(validator=my_validator, on="pre", method="validate")
+    ```
+
 ???+ note "Guard Examples"
 
     === "With message (short-circuit)"
@@ -200,23 +220,24 @@ The `Hook` base class allows creating custom hooks beyond guards. Implement `__c
 
 | Attribute | Description |
 |---|---|
-| `on` | `"pre"` (before forward) or `"post"` (after forward) |
+| `on` | `"pre"` (before execution) or `"post"` (after execution) |
 | `target` | Submodule name to register on. `None` = the module itself |
+| `method` | Method name to register on. `None` = the module execution boundary (`forward`) |
 | `processor_key` | Key for processor matching in `_set_hooks`. `None` = no processor |
-| `__call__` | Sync hook — called by `_call_impl` |
-| `acall` | Async hook — called by `_acall_impl` |
+| `__call__` | Sync hook — called by the sync hook dispatcher |
+| `acall` | Async hook — called by the async hook dispatcher |
 
 ### Hook Signatures
 
 ```python
-# Pre hook — receives module, args and kwargs before forward
+# Pre hook — receives module, args and kwargs before execution
 def __call__(self, module, args, kwargs, output=None): ...
 
-# Post hook — receives module, args, kwargs and the forward output
+# Post hook — receives module, args, kwargs and the output
 def __call__(self, module, args, kwargs, output=None): ...
 ```
 
-Both pre and post hooks share the same signature. For pre hooks, `output` is always `None`.
+Both pre and post hooks share the same signature. For pre hooks, `output` is always `None`. The same signature is used for forward hooks and method hooks.
 
 ???+ note "Custom Hook Examples"
 
@@ -253,6 +274,22 @@ Both pre and post hooks share the same signature. For pre hooks, `output` is alw
                 print(f"Generator took {elapsed:.2f}s")
         ```
 
+    === "Hooking an Internal Method"
+
+        ```python
+        from msgflux.nn.hooks import Hook
+
+        class PrepareResponseHook(Hook):
+            """Intercept Agent._prepare_response."""
+
+            def __init__(self):
+                super().__init__(on="post", method="_prepare_response")
+
+            def __call__(self, module, args, kwargs, output=None):
+                print("response_type:", kwargs["response_type"])
+                return output
+        ```
+
     === "Token Counter Hook"
 
         ```python
@@ -293,10 +330,11 @@ Both pre and post hooks share the same signature. For pre hooks, `output` is alw
 
 ### Hook Registration
 
-All `nn.Module` subclasses support the `hooks` class attribute. Each hook declares its own `target` — the submodule name where it registers:
+All `nn.Module` subclasses support the `hooks` class attribute. Each hook declares where it registers:
 
 - `target="generator"` (default for Guard) — registers on the internal `Generator` wrapper
 - `target=None` — registers on the module itself
+- `method="_prepare_response"` — registers on that specific method instead of `forward`
 
 ```python
 import msgflux.nn as nn
@@ -328,9 +366,27 @@ handle = guard.register(agent.generator)  # returns RemovableHandle
 handle.remove()  # unregister when done
 ```
 
+You can also register declarative hooks for a specific method via `hooks=`:
+
+```python
+from msgflux.nn.hooks import Hook
+
+class PrepareResponseHook(Hook):
+    def __init__(self):
+        super().__init__(on="post", method="_prepare_response")
+
+    def __call__(self, module, args, kwargs, output=None):
+        print("prepared response")
+        return output
+
+class Bot(nn.Agent):
+    model = model
+    hooks = [PrepareResponseHook()]
+```
+
 ### Using Hooks with `nn.Module` Directly
 
-The hook system is built into `nn.Module`. You can register hooks on any module via PyTorch-style methods:
+The hook system is built into `nn.Module`. You can register hooks on any module via PyTorch-style methods for `forward`, or via method hooks for other methods:
 
 ```python
 import msgflux.nn as nn
@@ -353,5 +409,39 @@ def my_post_hook(module, args, kwargs, output):
 handle = module.register_forward_hook(my_post_hook)
 ```
 
+### Registering Hooks on Arbitrary Methods
+
+Use `register_method_pre_hook()` and `register_method_hook()` when the extension point is an internal method rather than `forward`:
+
+```python
+import msgflux.nn as nn
+
+class MyModule(nn.Module):
+    def __init__(self):
+        super().__init__()
+
+    def forward(self, text):
+        return self._normalize(text)
+
+    def _normalize(self, text):
+        return text.strip().lower()
+
+module = MyModule()
+
+def normalize_pre_hook(module, args, kwargs):
+    return (args[0] + "  ",), kwargs
+
+def normalize_post_hook(module, args, kwargs, output):
+    return f"[{output}]"
+
+pre_handle = module.register_method_pre_hook("_normalize", normalize_pre_hook)
+post_handle = module.register_method_hook("_normalize", normalize_post_hook)
+
+result = module(" Hello ")
+print(result)  # "[hello]"
+```
+
+This is useful for methods such as `Agent._prepare_response`, `Agent._prepare_inputs`, or other internal extension points that do not warrant being promoted to standalone `Module` instances.
+
 !!! warning "Streaming Limitation"
     Guards with `on="post"` are **not compatible** with `stream=True`, since the full response is needed for validation. Using both raises a `ValueError` at initialization.

{msgflux-0.3.0 → msgflux-0.5.0}/docs/learn/nn/agent/index.md

@@ -25,6 +25,7 @@ An `Agent` combines a language model with instructions and tools to accomplish t
 | [Quick Start](quickstart.md) | Get started with a minimal agent, class-based definition (AutoParams) |
 | [Async](async.md) | Asynchronous agent execution |
 | [Streaming](streaming.md) | Real-time response streaming |
+| [Prompt Cache Warmup](prompt-cache.md) | Warm provider prompt caches with the system prompt and tool schemas |
 | [Reasoning](reasoning.md) | Model-level reasoning, `reasoning_in_response`, dual-queue streaming |
 | [How to Debug an Agent](debug.md) | Inspection and debugging tools |
 | [System Prompt Components](system-prompt.md) | Compose system prompts from components |
@@ -32,6 +33,7 @@ An `Agent` combines a language model with instructions and tools to accomplish t
 | [Task and Context](task-and-context.md) | Input handling, templates, multimodal, chat history |
 | [Vars](vars.md) | Unified execution variable space |
 | [Tools](tools.md) | Tool calling, configuration, MCP, agent-as-tool |
+| [Agent Skills](skills.md) | Reusable `SKILL.md` workflows loaded through progressive disclosure |
 | [Signatures](signatures.md) | Declarative input/output specifications |
 | [Hooks & Guards](hooks.md) | Input and output safety checks with configurable policy |
 | [Model Gateway](model-gateway.md) | Multi-model routing |

msgflux-0.5.0/docs/learn/nn/agent/prompt-cache.md

@@ -0,0 +1,159 @@
+# Prompt Cache Warmup
+
+Prompt warmup sends the agent's stable prompt prefix to the model provider before the first real task. Providers with prompt caching can prefill the system prompt and tool schemas, so the next request with the same prefix can start faster or report cached input tokens.
+
+Use warmup when your agent has a large static system prompt, many tools, or loaded skills. It is not a replacement for response caching: no task message is sent, no checkpoint is written, and no conversation history is updated.
+
+## Basic Usage
+
+```python
+# pip install msgflux[openai]
+import msgflux as mf
+import msgflux.nn as nn
+
+
+def lookup_ticket(ticket_id: str) -> str:
+    return f"{ticket_id}: open"
+
+
+class SupportAgent(nn.Agent):
+    model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+    system_message = """
+    You are a support agent.
+    Follow the escalation policy and use tools when needed.
+    """
+    tools = [lookup_ticket]
+
+
+agent = SupportAgent()
+
+# Sends only the rendered system prompt and tool schemas.
+agent.warmup_system_prompt()
+
+response = agent("Check ticket MSGFLUX-42")
+print(response)
+```
+
+## Async Usage
+
+```python
+agent = SupportAgent()
+
+await agent.awarmup_system_prompt()
+response = await agent.acall("Check ticket MSGFLUX-42")
+```
+
+## Fire And Forget
+
+Warmup can run in the background while the process continues initializing:
+
+```python
+agent = SupportAgent()
+
+agent.warmup_system_prompt(background=True)
+
+# Continue booting your CLI, server, or worker.
+```
+
+For async applications:
+
+```python
+await agent.awarmup_system_prompt(background=True)
+```
+
+Background warmup does not return the provider response. Errors are logged by the background task runner.
+
+## What Is Sent
+
+Warmup intentionally bypasses runtime state. It sends:
+
+- The rendered `system_prompt`
+- Tool schemas from the agent's `ToolLibrary`
+- The provider's configured warmup token limit
+
+It does not send:
+
+- User task messages
+- Chat history
+- Checkpointer state
+- Agent inbox notifications
+- Typed parsers or generation schemas
+- Response templates
+
+This keeps warmup focused on the stable prefix that providers can cache.
+
+## Runtime Vars
+
+If the system prompt uses runtime variables, pass the same `vars` you expect to use for the real request:
+
+```python
+agent.warmup_system_prompt(vars={"tenant": "acme"})
+
+response = agent(
+    "Summarize the ticket",
+    vars={"tenant": "acme"},
+)
+```
+
+Cache hits depend on the provider seeing the same prompt prefix. If the rendered system prompt changes between warmup and the real call, the provider may miss the cache.
+
+## Tool Filtering
+
+Warmup accepts the same `tool_filter` shape used by agent execution:
+
+```python
+agent.warmup_system_prompt(tool_filter={"allow": ["lookup_ticket"]})
+```
+
+Use this when the real request will also restrict tools. A different tool schema list changes the prompt prefix and can reduce cache hits.
+
+## Model Gateway
+
+When the agent uses a `ModelGateway`, warmup routes through the gateway and accepts `model_preference`:
+
+```python
+agent.warmup_system_prompt(model_preference="fast")
+```
+
+The selected model must support `warmup_system_prompt`.
+
+## Provider Token Limit
+
+OpenAI-compatible chat providers default to one generated token for warmup. This keeps the request cheap while still forcing the provider to process the prompt.
+
+Override it on the model if a provider needs a different minimum:
+
+```python
+model = mf.Model.chat_completion(
+    "openai/gpt-4.1-mini",
+    warmup_max_tokens=1,
+)
+```
+
+OpenAI Chat Completions and Groq reject zero completion tokens, so `0` is not a portable warmup value.
+
+## Reading Cache Usage
+
+The provider response is returned in foreground mode:
+
+```python
+raw_response = agent.warmup_system_prompt()
+print(raw_response.usage)
+```
+
+OpenAI reports prompt cache hits in usage metadata:
+
+- Chat Completions: `usage.prompt_tokens_details.cached_tokens`
+- Responses API: `usage.input_tokens_details.cached_tokens`
+
+msgflux currently implements this warmup path for chat completions.
+
+## Practical Guidance
+
+- Keep the warmup prefix stable.
+- Put large static instructions, tools, and skills before dynamic user content.
+- Warmup is most useful above the provider's prompt-cache threshold.
+- Do not expect warmup to persist conversation state.
+- Use foreground warmup during tests so failures are visible.
+- Use background warmup during app startup when failures should not block serving.
+