msgflux 0.1.1__tar.gz → 0.2.0__tar.gz

{msgflux-0.1.1 → msgflux-0.2.0}/.github/workflows/release-drafter.yml

@@ -13,9 +13,15 @@ permissions:
 
 jobs:
   update_release_draft:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - name: Update Release Draft
-        uses: release-drafter/release-drafter@v6
+        uses: release-drafter/release-drafter@v7
+        with:
+          commitish: ${{ github.event.pull_request.base.ref || github.ref_name }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

msgflux-0.2.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [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.1.1 → msgflux-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msgflux
-Version: 0.1.1
+Version: 0.2.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

{msgflux-0.1.1 → msgflux-0.2.0}/docs/learn/inline.md

@@ -78,6 +78,48 @@ flux = mf.Inline(
 )
 ```
 
+### Registry
+
+Instead of building the modules dict by hand, use `mf.Registry` to collect
+functions with a decorator and pass them as a `{name: callable}` mapping:
+
+```python
+import msgflux as mf
+
+modules = mf.Registry()
+
+@modules
+def prep(msg):
+    msg.ready = True
+
+@modules
+def feat_a(msg):
+    msg.score_a = 1
+
+@modules
+def feat_b(msg):
+    msg.score_b = 2
+
+@modules
+def combine(msg):
+    msg.total = msg.score_a + msg.score_b
+
+flux = mf.Inline(
+    "prep -> [feat_a, feat_b] -> combine",
+    modules.to_items(),  # {"prep": prep, "feat_a": feat_a, ...}
+)
+
+msg = mf.dotdict()
+msg = flux(msg)
+
+print(msg.ready)  # True
+print(msg.total)  # 3
+```
+
+The decorator captures each function's `__name__` automatically. Use
+`@modules(name="custom")` to override the registered name when the
+expression uses a different identifier.
+
 ---
 
 ## 3. **Execution**

{msgflux-0.1.1 → msgflux-0.2.0}/docs/learn/nn/agent/quickstart.md

@@ -68,6 +68,30 @@ Any `__init__` parameter can be set as a class attribute: `model`, `system_messa
 
 The `description` is especially useful when using an [agent as a tool](tools.md#agent-as-tool) — the calling agent uses it to understand what the tool-agent does.
 
+## String shorthand
+
+When you do not need to configure extra model parameters, you can pass a
+`"provider/model-id"` string directly as the `model` argument. msgFlux will
+call `Model.chat_completion` internally.
+
+???+ example
+
+    ```python
+    import msgflux.nn as nn
+
+    agent = nn.Agent("assistant", "openai/gpt-4.1-mini")
+
+    response = agent("What is the capital of France?")
+    print(response)  # "The capital of France is Paris."
+    ```
+
+The string shorthand also works when reassigning `agent.model` after
+construction:
+
+```python
+agent.model = "groq/llama-3.1-8b-instant"
+```
+
 ## Adding Tools
 
 Agents can call functions to interact with external systems. Any callable with type annotations and a docstring can be used as a tool:

{msgflux-0.1.1 → msgflux-0.2.0}/docs/learn/nn/agent/tools.md

@@ -241,6 +241,86 @@ When the model decides to use a tool, the Agent intercepts the response, execute
         response = agent("Tell me about the history of the Python programming language")
         ```
 
+### Registry
+
+Use `mf.Registry` to collect tools with a decorator instead of building a list by hand.
+This is especially useful when tools are spread across multiple files or when you want
+to keep them decoupled from the agent definition.
+
+```python
+import msgflux as mf
+
+tools = mf.Registry()
+
+@tools
+def add(a: float, b: float) -> str:
+    """Sum two numbers.
+
+    Args:
+        a: First number.
+        b: Second number.
+
+    Returns:
+        The result of the addition.
+    """
+    return f"{a} + {b} = {a + b}"
+
+@tools(name="multiply")
+def mul(a: float, b: float) -> str:
+    """Multiply two numbers.
+
+    Args:
+        a: First number.
+        b: Second number.
+
+    Returns:
+        The result of the multiplication.
+    """
+    return f"{a} * {b} = {a * b}"
+
+print(tools.to_list())   # [<function add ...>, <function mul ...>]
+print(tools.to_items())  # {"add": <function add ...>, "multiply": <function mul ...>}
+```
+
+The decorator captures the callable's name automatically (`.__name__` for functions,
+`.name` attribute if available). Pass `name=` to override:
+
+| Usage | Captured name |
+|-------|---------------|
+| `@tools` | `add` (from `__name__`) |
+| `@tools("custom")` | `custom` |
+| `@tools(name="custom")` | `custom` |
+
+Pass the registry directly to an Agent:
+
+```python
+import msgflux.nn as nn
+
+class Calculator(nn.Agent):
+    model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+    tools = tools.to_list()
+```
+
+You can have multiple independent registries — each is an isolated instance:
+
+```python
+read_tools = mf.Registry()
+write_tools = mf.Registry()
+
+@read_tools
+def get_data(key: str) -> str:
+    """Retrieve data by key."""
+    return f"value_for_{key}"
+
+@write_tools
+def save_data(key: str, value: str) -> str:
+    """Persist a key-value pair."""
+    return f"saved {key}={value}"
+
+print(len(read_tools))   # 1
+print(len(write_tools))  # 1
+```
+
 ### Writing Good Tools
 
 #### Tool Names
@@ -492,6 +572,173 @@ Control how the model selects tools.
         response = router("How do I handle errors in Rust?")
         ```
 
+!!! note "Interaction with `tool_filter`"
+
+    `tool_choice` is resolved after runtime filtering.
+
+    - If `tool_filter` removes a specific tool configured in `tool_choice`, the Agent falls back to `"auto"` for that request
+    - If `tool_filter` removes all tools, tool usage is disabled for that request
+
+### Runtime Tool Filtering
+
+Use `tool_filter` when you need to change which tools are exposed on a **per-request** basis, without rebuilding the agent.
+
+**Rules:**
+
+- `tool_filter` must contain exactly one key: `"allow"` or `"block"`
+- The value can be a single tool name or a list of tool names
+- `{"block": "*"}` disables all tools for that request
+- Runtime `tool_filter=...` overrides the value loaded from `message_fields`
+
+???+ example
+
+    === "Allow Only Specific Tools"
+
+        ```python
+        # pip install msgflux[openai]
+        import msgflux as mf
+        import msgflux.nn as nn
+
+        # mf.set_envs(OPENAI_API_KEY="...")
+
+        def web_search(query: str) -> str:
+            """Search the web."""
+            return f"Search results for: {query}"
+
+        def calculator(expression: str) -> str:
+            """Evaluate a math expression."""
+            return f"Computed: {expression}"
+
+        def browser(url: str) -> str:
+            """Open a web page."""
+            return f"Fetched: {url}"
+
+        class Assistant(nn.Agent):
+            model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+            tools = [web_search, calculator, browser]
+            config = {"verbose": True}
+
+        agent = Assistant()
+
+        response = agent(
+            "Search for the latest Python release and calculate 2 + 2",
+            tool_filter={"allow": ["web_search", "calculator"]},
+        )
+        ```
+
+    === "Block Specific Tools"
+
+        ```python
+        response = agent(
+            "Answer this without opening pages",
+            tool_filter={"block": "browser"},
+        )
+        ```
+
+    === "Disable All Tools Temporarily"
+
+        ```python
+        response = agent(
+            "Answer only from model knowledge",
+            tool_filter={"block": "*"},
+        )
+        ```
+
+### Tool Filter from Message
+
+You can also load `tool_filter` from the input `Message` using `message_fields`.
+
+This is useful when another module or router decides which tools should be available before the Agent runs.
+
+???+ example
+
+    ```python
+    # pip install msgflux[openai]
+    import msgflux as mf
+    import msgflux.nn as nn
+
+    # mf.set_envs(OPENAI_API_KEY="...")
+
+    def web_search(query: str) -> str:
+        """Search the web."""
+        return f"Search results for: {query}"
+
+    def calculator(expression: str) -> str:
+        """Evaluate a math expression."""
+        return f"Computed: {expression}"
+
+    class ControlledAgent(nn.Agent):
+        model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+        tools = [web_search, calculator]
+        message_fields = {
+            "task": "content",
+            "tool_filter": "control.tool_filter",
+        }
+
+    agent = ControlledAgent()
+
+    msg = mf.Message(content="What is 25 * 17?")
+    msg.set("control.tool_filter", {"allow": "calculator"})
+
+    response = agent(msg)
+    ```
+
+!!! tip
+
+    Runtime kwargs still take precedence:
+
+    ```python
+    response = agent(
+        msg,
+        tool_filter={"block": "*"},  # overrides msg.control.tool_filter
+    )
+    ```
+
+### Limiting Tool Loops
+
+Use `config["max_tool_turns"]` to cap how many **completed tool rounds** an Agent can execute in a single request.
+
+When the limit is reached:
+
+- The next attempted tool round is not executed
+- The Agent makes one more model call with tools disabled
+- The model gets a final chance to produce a plain answer
+
+This is useful to avoid runaway tool loops while still allowing a graceful final response.
+
+???+ example
+
+    ```python
+    # pip install msgflux[openai] wikipedia
+    import msgflux as mf
+    import msgflux.nn as nn
+
+    # mf.set_envs(OPENAI_API_KEY="...")
+
+    wikipedia = mf.Retriever.web_search("wikipedia")
+
+    class Researcher(nn.Agent):
+        model = mf.Model.chat_completion("openai/gpt-4.1-mini")
+        system_message = "Use tools when needed, but finish with a concise answer."
+        tools = [wikipedia]
+        config = {
+            "tool_choice": "auto",
+            "max_tool_turns": 2,
+            "verbose": True,
+        }
+
+    agent = Researcher()
+
+    response = agent("Compare Python and Ruby and keep the answer short")
+    ```
+
+!!! note
+
+    `max_tool_turns` is different from `tool_choice="none"`:
+
+    - `tool_choice="none"` disables tools from the start
+    - `max_tool_turns` allows some tool usage first, then forces a final no-tools round if the loop keeps going
+
 ### Async Tools
 
 When your agent runs asynchronously with `acall()`, prefer writing async tools as well. This ensures non-blocking execution and better performance when tools perform I/O operations.

{msgflux-0.1.1 → msgflux-0.2.0}/docs/learn/nn/speaker.md

@@ -41,6 +41,25 @@ The `nn.Speaker` module converts text into natural-sounding speech using text-to
         audio_path = speaker("Hello world")
         ```
 
+## String shorthand
+
+When you do not need to configure extra model parameters, you can pass a
+`"provider/model-id"` string directly as the `model` argument. msgFlux will
+call `Model.text_to_speech` internally.
+
+```python
+import msgflux.nn as nn
+
+speaker = nn.Speaker("openai/gpt-4o-mini-tts")
+audio_path = speaker("Hello world")
+```
+
+The shorthand also works when reassigning `speaker.model` after construction:
+
+```python
+speaker.model = "openai/gpt-4o-mini-tts"
+```
+
 ---
 
 ## 2. **Audio Formats**

{msgflux-0.1.1 → msgflux-0.2.0}/docs/learn/nn/transcriber.md

@@ -38,6 +38,26 @@ The `nn.Transcriber` module wraps speech-to-text models to **transcribe audio**
         result = transcriber("/path/to/audio.mp3")
         ```
 
+## String shorthand
+
+When you do not need to configure extra model parameters, you can pass a
+`"provider/model-id"` string directly as the `model` argument. msgFlux will
+call `Model.speech_to_text` internally.
+
+```python
+import msgflux.nn as nn
+
+transcriber = nn.Transcriber("openai/whisper-1")
+result = transcriber("/path/to/audio.mp3")
+```
+
+The shorthand also works when reassigning `transcriber.model` after
+construction:
+
+```python
+transcriber.model = "openai/whisper-1"
+```
+
 ---
 
 ## 2. **Input Types**

{msgflux-0.1.1 → msgflux-0.2.0}/scripts/release.sh

@@ -198,7 +198,8 @@ git checkout -b "$BRANCH_NAME"
 # Commit changes
 echo -e "${BLUE}💾 Committing changes...${NC}"
 git add src/msgflux/version.py CHANGELOG.md
-git commit -m "RELEASE: v$NEW_VERSION
+COMMIT_MSG=$(cat <<EOF
+RELEASE: v$NEW_VERSION
 
 This release updates:
 - version.py: $CURRENT_VERSION → $NEW_VERSION
@@ -208,10 +209,9 @@ After merging this PR:
 - publish.yml workflow will trigger automatically
 - Package will be built and published to PyPI
 - GitHub release will be created with tag v$NEW_VERSION
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>"
+EOF
+)
+git commit -m "$COMMIT_MSG"
 
 # Push release branch
 echo -e "${BLUE}📤 Pushing release branch...${NC}"
@@ -226,12 +226,8 @@ if [ "$ORIGIN_REPO" != "$BASE_REPO" ]; then
   PR_HEAD="${ORIGIN_OWNER}:${BRANCH_NAME}"
 fi
 
-PR_URL=$(gh pr create \
-  --repo "$BASE_REPO" \
-  --base main \
-  --head "$PR_HEAD" \
-  --title "$PR_TITLE" \
-  --body "## 🚀 Release v$NEW_VERSION
+PR_BODY=$(cat <<EOF
+## 🚀 Release v$NEW_VERSION
 
 ### Changes
 - **Version**: $CURRENT_VERSION → $NEW_VERSION
@@ -252,11 +248,16 @@ PR_URL=$(gh pr create \
 ### Merge Instructions
 After CI passes, merge this PR using one of:
 - Merge bot: Comment \`@mergebot merge\`
-- GitHub UI: Use \"Squash and merge\"
-
----
+- GitHub UI: Use "Squash and merge"
+EOF
+)
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)" \
+PR_URL=$(gh pr create \
+  --repo "$BASE_REPO" \
+  --base main \
+  --head "$PR_HEAD" \
+  --title "$PR_TITLE" \
+  --body "$PR_BODY" \
   --label "release" \
   --label "automerge")
 

{msgflux-0.1.1 → msgflux-0.2.0}/src/msgflux/__init__.py

@@ -8,6 +8,7 @@ if TYPE_CHECKING:
     from msgflux.core.dotdict import dotdict
     from msgflux.core.examples import Example
     from msgflux.core.message import Message
+    from msgflux.core.registry import Registry
     from msgflux.data.dbs import DB
     from msgflux.data.parsers import Parser
     from msgflux.data.retrievers import Retriever
@@ -40,6 +41,7 @@ __all__ = [
     "ModelGateway",
     "OutputField",
     "Parser",
+    "Registry",
     "Retriever",
     "Signature",
     "Spans",
@@ -72,6 +74,7 @@ _LAZY_IMPORTS = {
     "ModelGateway": ("msgflux.models.gateway", "ModelGateway"),
     "OutputField": ("msgflux.dsl.signature", "OutputField"),
     "Parser": ("msgflux.data.parsers", "Parser"),
+    "Registry": ("msgflux.core.registry", "Registry"),
     "Retriever": ("msgflux.data.retrievers", "Retriever"),
     "Signature": ("msgflux.dsl.signature", "Signature"),
     "Spans": ("msgflux.telemetry", "Spans"),

{msgflux-0.1.1 → msgflux-0.2.0}/src/msgflux/core/__init__.py

@@ -1,5 +1,6 @@
 from msgflux.core.dotdict import dotdict
 from msgflux.core.examples import Example, ExampleCollection
 from msgflux.core.message import Message
+from msgflux.core.registry import Registry
 
-__all__ = ["Example", "ExampleCollection", "Message", "dotdict"]
+__all__ = ["Example", "ExampleCollection", "Message", "Registry", "dotdict"]

msgflux-0.2.0/src/msgflux/core/registry.py

@@ -0,0 +1,126 @@
+from typing import Any, Callable, TypeVar, overload
+
+T = TypeVar("T", bound=Callable[..., Any])
+
+
+class Registry:
+    """Instance-based callable registry.
+
+    A decorator-based registry that collects callables (tools, modules, functions)
+    and exposes them as a list or a name-to-callable dict.
+
+    Examples
+    --------
+    Register tools for an Agent::
+
+        tools = Registry()
+
+        @tools
+        def search(query: str) -> str: ...
+
+        @tools(name="web_fetch")
+        def fetch(url: str) -> str: ...
+
+        agent = Agent(tools=tools.to_list())
+
+    Register modules for Inline::
+
+        modules = Registry()
+
+        @modules(name="summarizer")
+        class Summarizer(Module): ...
+
+        pipeline = Inline(modules=modules.to_items())
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[str, Any] = {}
+
+    def _resolve_name(self, obj: Any) -> str:
+        """Extract a registration name from a callable-like object."""
+        if hasattr(obj, "name"):
+            name = obj.name
+            if callable(name) and not isinstance(name, str):
+                name = name()
+            if isinstance(name, str) and name:
+                return name
+
+        dunder_name = getattr(obj, "__name__", None)
+        if isinstance(dunder_name, str) and dunder_name:
+            return dunder_name
+        raise TypeError(
+            "Unable to resolve a registry name. Provide `name=` or define `.name` "
+            "or `.__name__` on the registered object."
+        )
+
+    @overload
+    def __call__(self, obj: T) -> T: ...
+
+    @overload
+    def __call__(self, *, name: str) -> Callable[[T], T]: ...
+
+    @overload
+    def __call__(self, name: str) -> Callable[[T], T]: ...
+
+    def __call__(
+        self,
+        obj: T | str | None = None,
+        *,
+        name: str | None = None,
+    ) -> T | Callable[[T], T]:
+        # @registry
+        if obj is not None and callable(obj) and not isinstance(obj, str):
+            resolved = self._resolve_name(obj)
+            self._entries[resolved] = obj
+            return obj
+
+        # @registry("custom_name") or @registry(name="custom_name")
+        explicit_name = obj if isinstance(obj, str) else name
+
+        def decorator(fn: T) -> T:
+            key = explicit_name if explicit_name else self._resolve_name(fn)
+            self._entries[key] = fn
+            return fn
+
+        return decorator
+
+    def to_list(self) -> list[Any]:
+        """Return registered callables as a list."""
+        return list(self._entries.values())
+
+    def to_items(self) -> dict[str, Any]:
+        """Return registered callables as a ``{name: callable}`` dict."""
+        return dict(self._entries)
+
+    def update(self, other: "Registry") -> "Registry":
+        """Merge entries from *other* into this registry.
+
+        Returns ``self`` for chaining.
+        """
+        self._entries.update(other._entries)
+        return self
+
+    def get(self, name: str) -> Any:
+        """Return a single registered callable by name."""
+        return self._entries[name]
+
+    def pop(self, name: str) -> Any:
+        """Remove and return the callable registered under *name*."""
+        return self._entries.pop(name)
+
+    def clear(self) -> None:
+        """Remove all entries."""
+        self._entries.clear()
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._entries
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __iter__(self):
+        return iter(self._entries.values())
+
+    def __repr__(self) -> str:
+        names = list(self._entries.keys())
+        return f"Registry({names})"