msgflux 0.3.0__tar.gz → 0.4.1__tar.gz

{msgflux-0.3.0 → msgflux-0.4.1}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [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).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msgflux
-Version: 0.3.0
+Version: 0.4.1
 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

{msgflux-0.3.0 → msgflux-0.4.1}/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,13 @@ hide:
 
 ### Web Search
 
-| Provider    | Dependency    |
-|-------------|---------------|
-| Wikipedia   | `wikipedia`   |
+| Provider    | Installation                     | Auth Env                         |
+|-------------|----------------------------------|-----------------------------------|
+| Trafilatura | `httpx`, `trafilatura`           |                                   |
+| SerpApi     | `httpx`                          | `SERPAPI_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.4.1}/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.4.1}/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,10 @@ 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.
+
 ## 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.
@@ -736,6 +741,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 +801,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.4.1}/docs/learn/nn/agent/tools.md

@@ -218,6 +218,60 @@ When the model decides to use a tool, the Agent intercepts the response, execute
         response = agent("Summarize the main points from https://news.ycombinator.com")
         ```
 
+    === "Web Search"
+
+        Use a built-in web search tool backed by either a retriever or a model:
+
+        ```python
+        # pip install msgflux[openai]
+        import msgflux as mf
+        import msgflux.nn as nn
+        from msgflux.tools.builtin import WebSearch
+
+        # Option 1: retriever-backed web search
+        wikipedia_search = WebSearch(
+            "retriever/wikipedia",
+            call_params={"top_k": 2},
+        )
+
+        # Option 2: model-backed web search
+        openai_search = WebSearch(
+            "model/openai/gpt-4o-search-preview",
+            init_params={
+                "web_search_options": {"search_context_size": "low"},
+            },
+        )
+
+        # Or read the engine and params from the environment:
+        # export MSGFLUX_TOOL_WEB_SEARCH_ENGINE="retriever/wikipedia"
+        # export MSGFLUX_TOOL_WEB_SEARCH_INIT_PARAMS='{"language": "pt"}'
+        # export MSGFLUX_TOOL_WEB_SEARCH_CALL_PARAMS='{"top_k": 2}'
+        env_search = WebSearch()
+
+        class Researcher(nn.Agent):
+            model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+            system_message = "You help users find up-to-date information."
+            tools = [wikipedia_search, openai_search, env_search]
+            config = {"verbose": True}
+
+        agent = Researcher()
+
+        result = agent("What is the latest Python version?")
+        ```
+
+        The tool returns a `dict` with:
+
+        - `data`: the search result payload
+        - `annotations`: citation metadata when available
+
+        `init_params` is unpacked into the backend constructor
+        (`Retriever.web_search(...)` or `Model.chat_completion(...)`).
+        `call_params` is supported only for retriever engines and is unpacked
+        whenever the retriever is called. If these values are not passed
+        explicitly, `WebSearch` reads the JSON objects from
+        `MSGFLUX_TOOL_WEB_SEARCH_INIT_PARAMS` and
+        `MSGFLUX_TOOL_WEB_SEARCH_CALL_PARAMS`.
+
     === "Wikipedia Search"
 
         Use msgflux's built-in Wikipedia retriever as a tool: