msgflux 0.1.0a1__tar.gz

msgflux-0.1.0a1/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# See https://help.github.com/articles/about-codeowners/
+# for more info about CODEOWNERS file
+
+# CODEOWNERS
+* @vilsonrodrigues

msgflux-0.1.0a1/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"

msgflux-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,119 @@
+name: Release
+
+# Dynamic run name that appears in the GitHub UI
+run-name: Release version ${{ github.ref_name }} of the SDK
+
+on:
+  # no explicit inputs for tag_name; rely on the selected reference from the UI
+  workflow_dispatch:
+
+# ensures only a single instance of this release workflow is running at any one time
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: true
+
+env:
+  PACKAGE_NAME: "msgspec-ext"
+  TEST_PYPI_URL: "https://test.pypi.org/pypi"
+  PYPI_URL: "https://pypi.org/pypi"
+
+jobs:
+  get_tag_details:
+    name: Get Tag Details
+    runs-on: msgflux-python-runner
+    outputs:
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      new_version: ${{ steps.release.outputs.new_version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # fetch all history
+
+      - name: Check if a tag is selected
+        run: |
+          if [ "${{ github.ref_type }}" != "tag" ]; then
+            echo "Error: Workflow must be triggered with a tag selected. Current ref_type is ${{ github.ref_type }}."
+            exit 1
+          fi
+          TAG_NAME=${{ github.ref_name }}
+          echo "Selected tag is $TAG_NAME"
+
+      - name: Extract version from tag
+        id: release
+        run: |
+          TAG_NAME=${{ github.ref_name }}
+          # Validate tag format
+          if [[ ! $TAG_NAME =~ ^v[0-9]+\.[0-9]+\.[0-9]+(a[0-9]+|b[0-9]+|rc[0-9]+)?$ ]]; then
+            echo "Invalid tag format. Tag must be in the format vX.Y.Z, vX.Y.ZaN, vX.Y.ZbN, or vX.Y.ZrcN."
+            exit 1
+          fi
+          NEW_VERSION=${TAG_NAME#v}
+          echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+          echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Tag name is $TAG_NAME"
+          echo "Version is $NEW_VERSION"
+
+  setup_build_and_publish:
+    name: Build Package and Publish to PyPI
+    needs: [get_tag_details]
+    runs-on: msgflux-python-runner
+    permissions:
+      contents: read
+      id-token: write # Required for trusted publishing to PyPI
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c7f87aa956e4c323abf06d5dec078e358f6b4d04 # v6
+        with:
+          version: "0.7.3"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Build source and wheel distribution
+        run: |
+          uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Publish to PyPI
+        run: uv publish
+
+  github_release:
+    name: Create GitHub Release
+    needs: [get_tag_details, setup_build_and_publish]
+    runs-on: msgflux-python-runner
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        id: create_release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create ${{ needs.get_tag_details.outputs.tag_name }} dist/* --title ${{ needs.get_tag_details.outputs.tag_name }} --generate-notes

msgflux-0.1.0a1/.gitignore

@@ -0,0 +1,25 @@
+env/
+.env
+venv/
+.venv
+.envrc
+env3*/
+Pipfile
+*.lock
+*.py[cod]
+*.egg-info/
+/build/
+dist/
+.cache/
+/site/
+/site.zip
+.pytest_cache/
+.python-version
+__pycache__/
+.vscode/
+_build/
+.auto-format
+/sandbox/
+/worktrees/
+/.ruff_cache/
+.DS_Store

msgflux-0.1.0a1/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.23.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/astral-sh/uv-pre-commit    
+    rev: 0.8.3 # uv version.
+    hooks:
+      - id: uv-lock
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

msgflux-0.1.0a1/.readthedocs.yaml

@@ -0,0 +1,12 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yaml

msgflux-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 msgflux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

msgflux-0.1.0a1/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: msgflux
+Version: 0.1.0a1
+Summary: Messages and Dynamic AI Systems in Python powered by pretrained models
+Project-URL: Homepage, https://github.com/msgflux/msgspec-ext
+Project-URL: Documentation, https://github.com/msgflux/msgspec-ext
+Project-URL: Repository, https://github.com/msgflux/msgspec-ext
+Author-email: Vilson Rodrigues <vilson@msgflux.com>
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Requires-Dist: code2mermaid>=0.3.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mermaid-py>=0.8.0
+Requires-Dist: msgspec-ext>=0.1.0
+Requires-Dist: opentelemetry-api>=1.35.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.35.0
+Requires-Dist: opentelemetry-sdk>=1.35.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typing-extensions>=4.14.1
+Requires-Dist: uvloop>=0.21.0
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.28.1; extra == 'httpx'
+Provides-Extra: openai
+Requires-Dist: openai>=1.97.1; extra == 'openai'
+Requires-Dist: opentelemetry-instrumentation-openai>=0.43.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# msgFlux

msgflux-0.1.0a1/README.md

@@ -0,0 +1 @@
+# msgFlux

msgflux-0.1.0a1/pyproject.toml

@@ -0,0 +1,141 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "msgflux"
+dynamic = ["version"]
+description = "Messages and Dynamic AI Systems in Python powered by pretrained models"
+readme = "README.md"
+authors = [
+    { name = "Vilson Rodrigues", email = "vilson@msgflux.com" }
+]
+requires-python = ">=3.9"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",  
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Information Analysis"
+]
+dependencies = [
+    "code2mermaid>=0.3.0",
+    "jinja2>=3.1.6",
+    "mermaid-py>=0.8.0",
+    "msgspec-ext>=0.1.0",
+    "opentelemetry-api>=1.35.0",
+    "opentelemetry-exporter-otlp>=1.35.0",
+    "opentelemetry-sdk>=1.35.0",
+    "tenacity>=9.1.2",
+    "tomli-w>=1.2.0",
+    "typing-extensions>=4.14.1",
+    "uvloop>=0.21.0",
+]
+
+[tool.hatch.version]
+path = "src/msgflux/version.py"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "pytest-cov>=6.2.1",
+    "ruff>=0.12.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/msgflux/msgspec-ext"
+Documentation = "https://github.com/msgflux/msgspec-ext"
+Repository = "https://github.com/msgflux/msgspec-ext"
+
+[project.optional-dependencies]
+openai = [
+    "openai>=1.97.1",
+    "opentelemetry-instrumentation-openai>=0.43.1",
+]
+httpx = [
+    "httpx>=0.28.1",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+  "A",
+  "ARG",
+  "B",
+  "C",
+  "D",
+  "DTZ",
+  "E",
+  "EM",
+  "F",
+  "FBT",
+  "I",
+  "ICN",
+  "ISC",
+  "N",
+  "PLC",
+  "PLE",
+  "PLR",
+  "PLW",
+  "Q",
+  "RUF",
+  "S",
+  "T",
+  "TID",
+  "UP",
+  "W",
+  "YTT",
+]
+ignore = [
+  "D100",    # Allow missing docstring in top level module
+  "D104",    # Allow missing docstring in public package
+  "D105",    # Allow missing docstring in magic method
+  "D203",    # Allow docstring directly below class definition (as enforced by D211)
+  "D213",    # Allow multi-line-summary on first line of docstring (as enforced by D212)
+  "D401",    # Allow non imperative mood in docstring
+  "D413",    # Allow no new line at end of docstring.
+  "EM101",   # Allow `raise ValueError(msg)`
+  "EM102",   # Allow f strings in `raise` statements
+  "FBT003",  # Allow boolean positional values in function calls, like `dict.get(... True)`
+  "TID252",  # Allow relative imports
+  "UP007",   # Allow `from typing import Optional` instead of `X | None`
+  "UP035",   # Allow `from typing import Sequence` instead of `Sequence[X]`
+  "PLR0913",
+]
+unfixable = ["F401"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["msgflux"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = [
+  "D",
+  "PLR0911",
+  "PLR0912",
+  "PLR0915",
+  "PLR2004",
+  "S101",
+  "S105",
+  "S106",
+  "S107",
+  "TID252",
+]

msgflux-0.1.0a1/src/msgflux/__init__.py

@@ -0,0 +1,37 @@
+from .cache import response_cache
+from .data.databases.database import DataBase
+from .data.retrievers.retriever import Retriever
+from .dotdict import dotdict
+from .dsl.inline import inline
+from .dsl.signature import InputField, OutputField, Signature
+from .envs import set_envs
+from .message import Message
+from .models.gateway import ModelGateway
+from .models.model import Model
+from .utils.chat import ChatML
+from .utils.inspect import get_fn_name
+from .utils.msgspec import load, save
+from .utils.tool import tool_config
+from .telemetry.span import instrument
+
+
+__all__ = [
+    "ChatML",
+    "DataBase",  
+    "InputField",
+    "Message",
+    "Model",
+    "ModelGateway",
+    "OutputField",
+    "Retriever",    
+    "Signature",
+    "dotdict",
+    "get_fn_name",
+    "inline",
+    "instrument",  
+    "load",
+    "response_cache",
+    "save",
+    "set_envs",
+    "tool_config"
+]

msgflux-0.1.0a1/src/msgflux/_private/client.py

@@ -0,0 +1,91 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+from msgflux._private.core import Core
+
+
+class BaseClient(ABC, Core):
+    """
+    BaseClient is an abstract base class that defines the interface and common behavior
+    for client classes in the msgflux system.
+
+    This class inherits from `Core` to leverage its state management capabilities and
+    extends it with additional functionality specific to clients. It requires subclasses
+    to implement certain methods, ensuring a consistent interface across different client
+    implementations.
+
+    Subclasses must implement the `_initialize` and `__call__` methods, which are
+    essential for client initialization and operation, respectively. Additionally, this
+    class provides methods for serialization and deserialization, allowing client instances
+    to be easily saved and restored.
+
+    Attributes:
+        to_ignore ([optional[list[str]]): A list of attribute keys to be ignored during serialization.
+        msgflux_type (str): A string identifying the type of the client in the msgflux system.
+        provider (optional[str]): The provider associated with the client, if applicable.
+        instance_type (optional[callable]): A method or callable that returns additional
+            instance-specific data to be included during serialization.
+    """
+
+    @abstractmethod
+    def __call__(self):
+        """
+        Execute the client's main functionality. This method must be implemented by subclasses.
+
+        This method defines the primary behavior of the client and is called when the instance
+        is invoked as a function.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """
+        raise NotImplementedError
+
+    async def acall(self, *args, **kwargs):
+        """ Async interface to __call__ """
+        return self.__call__(*args, **kwargs)
+
+    def serialize(self) -> Dict[str, Any]:
+        """
+        Serialize the client instance into a dictionary.
+
+        This method prepares the client's state for serialization by removing unnecessary
+        attributes and including additional metadata such as the client type and provider.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the serialized state of the client,
+            including metadata and the client's internal state.
+        """
+        state =  self.__getstate__()
+        if hasattr(self, "to_ignore"):
+            for key in self.to_ignore:
+                state.pop(key, None)
+        data = {"msgflux_type": self.msgflux_type}
+        if hasattr(self, "provider"):
+            data["provider"] = self.provider
+        if hasattr(self, "instance_type"):
+            instance_type = self.instance_type()
+            data.update(instance_type)
+        data["state"] = state
+        return data     
+
+    @classmethod
+    def from_serialized(cls, state: Dict[str, Any]):
+        """
+        Deserialize a client instance from a dictionary.
+
+        This method creates a new instance of the client and restores its state from the
+        provided dictionary. It also ensures that the client is properly initialized
+        after deserialization.
+
+        Args:
+            state (Dict[str, Any]): A dictionary containing the serialized state of the client.
+
+        Returns:
+            BaseClient: A new instance of the client with its state restored.
+        """
+        if "msgflux_type" in state:
+            state.pop("msgflux_type")
+        instance = cls()
+        instance.__setstate__(state)
+        if hasattr(instance, "_initialize"):        
+            instance._initialize()
+        return instance

msgflux-0.1.0a1/src/msgflux/_private/core.py

@@ -0,0 +1,14 @@
+class Core:
+    """ 
+    Core is a set of methods that are common among some classes in msgflux.
+    
+    This class provides basic functionality for state management, allowing instances
+    to be serialized and deserialized. It is intended to be inherited by other classes
+    that require these common features.
+    """
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        return state
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)

msgflux-0.1.0a1/src/msgflux/_private/executor.py

@@ -0,0 +1,77 @@
+import asyncio
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
+import uvloop
+from msgflux.envs import envs
+
+
+class AsyncWorker:
+    def __init__(self):
+        """Initializes a worker with its own event loop in a separate thread."""
+        self.loop = uvloop.new_event_loop()
+        self.thread = threading.Thread(target=self.loop.run_forever)
+        self.thread.start()
+
+    def submit(self, coro):
+        """Submits a coroutine to the worker's event loop."""
+        return asyncio.run_coroutine_threadsafe(coro, self.loop)
+
+    def shutdown(self):
+        """Terminates the event loop and worker thread."""
+        self.loop.call_soon_threadsafe(self.loop.stop)
+        self.thread.join()
+
+
+class Executor:
+    """
+    Async pool to manage the execution of synchronous and asynchronous code.
+    Executor distributes tasks among a ThreadPool or among Async Workers.
+    """    
+    _instance = None
+    _lock = threading.Lock()    
+
+    def __init__(self):
+        self.num_threads = envs.executor_num_threads
+        self.num_async_workers = envs.executor_num_async_workers
+        self.async_worker_index = 0
+        self.thread_pool = ThreadPoolExecutor(max_workers=self.num_threads)
+        self.async_workers = [AsyncWorker() for _ in range(self.num_async_workers)]
+
+    @classmethod
+    def get_instance(cls):
+        """Returns the singleton instance in a thread-safe manner."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def submit(self, f: Callable, *args, **kwargs):
+        """
+        Submits a task to the appropriate pool based on the function type.
+        Returns a Future to track the result.
+        """
+        if hasattr(f, "acall"):
+            coro = f.acall(*args, **kwargs)
+            return self._submit_to_async_worker(coro)
+        elif asyncio.iscoroutinefunction(f):
+            coro = f(*args, **kwargs)
+            return self._submit_to_async_worker(coro)
+        else:
+            return self.thread_pool.submit(f, *args, **kwargs)
+
+    def _submit_to_async_worker(self, coro):
+        """Distribute a coroutine to an asynchronous worker using round-robin."""
+        worker = self.async_workers[self.async_worker_index]
+        self.async_worker_index = (self.async_worker_index + 1) % self.num_async_workers
+        return worker.submit(coro)
+
+    def shutdown(self):
+        """Shutdown the executor, closing the pools."""
+        self.thread_pool.shutdown()
+        for worker in self.async_workers:
+            worker.shutdown()
+
+    def __del__(self):
+        self.shutdown()

msgflux-0.1.0a1/src/msgflux/cache.py

@@ -0,0 +1,50 @@
+from functools import wraps
+from typing import Optional
+from msgflux.data.databases.base import BaseDB
+from msgflux.message import Message
+from msgflux.models.types import TextEmbedderModel
+
+
+def response_cache(
+    db: BaseDB, 
+    task_inputs: Optional[str] = None, 
+    response_mode: Optional[str] = None,
+    model: Optional[TextEmbedderModel] = None,
+):
+    def decorator(func):        
+        @wraps(func)
+        def wrapper(msg):
+            if isinstance(msg, Message):
+                if task_inputs is None:
+                    raise ValueError(
+                        "`task_inputs` is required when input "
+                        "is a Message instance"
+                    )
+                key = msg.get(task_inputs)
+            else:
+                key = msg
+
+            if model:
+                key = model(key)            
+
+            cached_response = db(key)
+            
+            if cached_response is not None:
+                if isinstance(msg, Message):
+                    if response_mode is None:
+                        raise ValueError(
+                            "`response_mode` is required when "
+                            "input is a Message instance"
+                        )
+                    msg.set(response_mode, cached_response)
+                    return msg
+                return cached_response
+            
+            response = func(msg)
+            
+            if response is not None:
+                db.add(key, response)
+
+            return response
+        return wrapper
+    return decorator

msgflux-0.1.0a1/src/msgflux/data/audio.py

@@ -0,0 +1 @@
+#https://github.com/openai/openai-python/blob/384e6b23ce0366d6b2f31cc98d35525da5b22c10/src/openai/helpers/local_audio_player.py#L19