agent-routers 0.1.0__tar.gz

agent_routers-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Routers
+
+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.

agent_routers-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: agent-routers
+Version: 0.1.0
+Summary: Priority-based async/sync routing engine for multi-agent systems
+Author: Michael Douglas Barbosa Araujo
+License: MIT
+Project-URL: Homepage, https://agentrouters.github.io/docs/
+Project-URL: Issues, https://github.com/seuusuario/agent-routers/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Agent Routers
+
+> Deterministic, priority-based routing engine for multi-agent systems.
+
+Agent Routers is a lightweight Python library for building rule-based routing layers.
+It allows you to register sync or async handlers and dispatch inputs using
+priority-aware regex matching — without requiring LLMs or web frameworks.
+
+---
+
+## Why Agent Routers?
+
+- Supports **sync and async handlers**
+- Deterministic, priority-based rule resolution
+- Perfect for multi-agent supervisors and orchestration layers
+- Minimal overhead, zero external dependencies
+
+---
+
+## Installation
+
+```bash
+pip install agent-routers
+```

agent_routers-0.1.0/README.md

@@ -0,0 +1,24 @@
+# Agent Routers
+
+> Deterministic, priority-based routing engine for multi-agent systems.
+
+Agent Routers is a lightweight Python library for building rule-based routing layers.
+It allows you to register sync or async handlers and dispatch inputs using
+priority-aware regex matching — without requiring LLMs or web frameworks.
+
+---
+
+## Why Agent Routers?
+
+- Supports **sync and async handlers**
+- Deterministic, priority-based rule resolution
+- Perfect for multi-agent supervisors and orchestration layers
+- Minimal overhead, zero external dependencies
+
+---
+
+## Installation
+
+```bash
+pip install agent-routers
+```

agent_routers-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "agent-routers"
+version = "0.1.0"
+description = "Priority-based async/sync routing engine for multi-agent systems"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [ ]
+
+
+[project.license]
+text = "MIT"
+
+
+[[project.authors]]
+name = "Michael Douglas Barbosa Araujo"
+
+
+[project.urls]
+Homepage = "https://agentrouters.github.io/docs/"
+Issues = "https://github.com/seuusuario/agent-routers/issues"
+
+
+[build-system]
+requires = [ "setuptools>=61.0", "wheel" ]
+build-backend = "setuptools.build_meta"
+
+
+[dependency-groups]
+dev = [ "pytest-asyncio>=1.3.0" ]

agent_routers-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_routers-0.1.0/src/agent_routers/__init__.py

@@ -0,0 +1,13 @@
+from .router import AgentRouter
+from .exceptions import (
+    AgentRouterError,
+    NoAgentMatchedError,
+    AgentAlreadyRegisteredError,
+)
+
+__all__ = [
+    "AgentRouter",
+    "AgentRouterError",
+    "NoAgentMatchedError",
+    "AgentAlreadyRegisteredError",
+]

agent_routers-0.1.0/src/agent_routers/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Custom exceptions for agent_routers.
+
+This module centralizes all library-specific errors,
+making error handling predictable and explicit.
+"""
+
+
+class AgentRouterError(Exception):
+    """Base exception for all agent_routers errors."""
+    pass
+
+
+class NoAgentMatchedError(AgentRouterError):
+    """
+    Raised when no registered agent matches the given input.
+
+    Attributes:
+        input_text (str): The input that failed routing.
+    """
+
+    def __init__(self, input_text: str):
+        self.input_text = input_text
+        super().__init__(f"No agent matched the input: '{input_text}'")
+
+
+class AgentAlreadyRegisteredError(AgentRouterError):
+    """
+    Raised when trying to register an agent that already exists.
+
+    Attributes:
+        agent_name (str): The duplicate agent name.
+    """
+
+    def __init__(self, agent_name: str):
+        self.agent_name = agent_name
+        super().__init__(f"Agent '{agent_name}' is already registered.")
+
+
+class InvalidRuleError(AgentRouterError):
+    """
+    Raised when a rule definition is invalid (e.g., malformed regex).
+
+    Attributes:
+        rule (str): The invalid rule definition.
+    """
+
+    def __init__(self, rule: str):
+        self.rule = rule
+        super().__init__(f"Invalid rule provided: '{rule}'")

agent_routers-0.1.0/src/agent_routers/logging.py

@@ -0,0 +1,10 @@
+import time
+
+
+def log_decision(input_text: str, agent_name: str, layer: str):
+    print({
+        "input": input_text,
+        "agent": agent_name,
+        "layer": layer,
+        "timestamp": time.time()
+    })

agent_routers-0.1.0/src/agent_routers/models.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from typing import Callable, Awaitable, Union, Any
+import re
+
+
+Handler = Union[
+    Callable[[str], Any],
+    Callable[[str], Awaitable[Any]],
+]
+
+
+@dataclass(order=True)
+class Rule:
+    """
+    Represents a routing rule.
+
+    Rules are ordered by priority (descending).
+    """
+    priority: int
+    name: str = field(compare=False)
+    pattern: str = field(compare=False)
+    handler: Handler = field(compare=False)
+    compiled_pattern: re.Pattern = field(init=False, compare=False)
+
+    def __post_init__(self):
+        self.compiled_pattern = re.compile(self.pattern)

agent_routers-0.1.0/src/agent_routers/registry.py

@@ -0,0 +1,21 @@
+from typing import Dict, List
+from .models import Agent
+
+
+class AgentRegistry:
+
+    def __init__(self):
+        self._agents: Dict[str, Agent] = {}
+
+    def register(self, agent: Agent):
+        if agent.name in self._agents:
+            raise ValueError(f"Agent '{agent.name}' already registered.")
+        self._agents[agent.name] = agent
+
+    def get(self, name: str) -> Agent:
+        if name not in self._agents:
+            raise ValueError(f"Agent '{name}' not found.")
+        return self._agents[name]
+
+    def list_names(self) -> List[str]:
+        return list(self._agents.keys())

agent_routers-0.1.0/src/agent_routers/router.py

@@ -0,0 +1,54 @@
+import inspect
+from typing import List, Any
+
+from .models import Rule
+from .exceptions import (
+    NoAgentMatchedError,
+    AgentAlreadyRegisteredError,
+)
+
+
+class AgentRouter:
+    """
+    Async-first agent router with priority-based matching.
+    """
+
+    def __init__(self) -> None:
+        self._rules: List[Rule] = []
+        self._registered_names = set()
+
+    def register(
+        self,
+        name: str,
+        pattern: str,
+        handler,
+        priority: int = 0,
+    ) -> None:
+
+        if name in self._registered_names:
+            raise AgentAlreadyRegisteredError(name)
+
+        rule = Rule(
+            priority=priority,
+            name=name,
+            pattern=pattern,
+            handler=handler,
+        )
+
+        self._rules.append(rule)
+        self._registered_names.add(name)
+
+        # Sort once when registering (descending priority)
+        self._rules.sort(reverse=True)
+
+    async def route(self, input_text: str) -> Any:
+
+        for rule in self._rules:
+            if rule.compiled_pattern.search(input_text):
+
+                if inspect.iscoroutinefunction(rule.handler):
+                    return await rule.handler(input_text)
+
+                return rule.handler(input_text)
+
+        raise NoAgentMatchedError(input_text)

agent_routers-0.1.0/src/agent_routers/rules.py

@@ -0,0 +1,17 @@
+import re
+from typing import Optional, Dict
+
+
+class RegexClassifier:
+
+    def __init__(self):
+        self._rules: Dict[str, str] = {}
+
+    def add_rule(self, pattern: str, agent_name: str):
+        self._rules[pattern] = agent_name
+
+    def classify(self, text: str) -> Optional[str]:
+        for pattern, agent_name in self._rules.items():
+            if re.search(pattern, text, re.IGNORECASE):
+                return agent_name
+        return None

agent_routers-0.1.0/src/agent_routers.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: agent-routers
+Version: 0.1.0
+Summary: Priority-based async/sync routing engine for multi-agent systems
+Author: Michael Douglas Barbosa Araujo
+License: MIT
+Project-URL: Homepage, https://agentrouters.github.io/docs/
+Project-URL: Issues, https://github.com/seuusuario/agent-routers/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Agent Routers
+
+> Deterministic, priority-based routing engine for multi-agent systems.
+
+Agent Routers is a lightweight Python library for building rule-based routing layers.
+It allows you to register sync or async handlers and dispatch inputs using
+priority-aware regex matching — without requiring LLMs or web frameworks.
+
+---
+
+## Why Agent Routers?
+
+- Supports **sync and async handlers**
+- Deterministic, priority-based rule resolution
+- Perfect for multi-agent supervisors and orchestration layers
+- Minimal overhead, zero external dependencies
+
+---
+
+## Installation
+
+```bash
+pip install agent-routers
+```

agent_routers-0.1.0/src/agent_routers.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/agent_routers/__init__.py
+src/agent_routers/exceptions.py
+src/agent_routers/logging.py
+src/agent_routers/models.py
+src/agent_routers/registry.py
+src/agent_routers/router.py
+src/agent_routers/rules.py
+src/agent_routers.egg-info/PKG-INFO
+src/agent_routers.egg-info/SOURCES.txt
+src/agent_routers.egg-info/dependency_links.txt
+src/agent_routers.egg-info/top_level.txt
+tests/test_router.py

agent_routers-0.1.0/src/agent_routers.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_routers-0.1.0/src/agent_routers.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_routers

agent_routers-0.1.0/tests/test_router.py

@@ -0,0 +1,162 @@
+import pytest
+from agent_routers import AgentRouter
+from agent_routers.exceptions import (
+    NoAgentMatchedError,
+    AgentAlreadyRegisteredError,
+)
+
+
+# ---------------------------
+# Async Handler
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_async_handler_routing():
+
+    async def support_handler(text: str):
+        return "support called"
+
+    router = AgentRouter()
+    router.register("support", r"error|bug", support_handler)
+
+    result = await router.route("There is an error")
+
+    assert result == "support called"
+
+
+# ---------------------------
+# Sync Handler
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_sync_handler_routing():
+
+    def greet_handler(text: str):
+        return "hello"
+
+    router = AgentRouter()
+    router.register("greet", r"hello|hi", greet_handler)
+
+    result = await router.route("hello world")
+
+    assert result == "hello"
+
+
+# ---------------------------
+# No Match
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_no_agent_matched():
+
+    router = AgentRouter()
+
+    with pytest.raises(NoAgentMatchedError):
+        await router.route("nothing matches this")
+
+
+# ---------------------------
+# Duplicate Agent Registration
+# ---------------------------
+
+def test_duplicate_agent_registration():
+
+    def handler(text: str):
+        return "x"
+
+    router = AgentRouter()
+    router.register("agent1", r"test", handler)
+
+    with pytest.raises(AgentAlreadyRegisteredError):
+        router.register("agent1", r"other", handler)
+
+
+# ---------------------------
+# Same Priority → First Registered Wins
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_same_priority_first_registered_wins():
+
+    def handler1(text: str):
+        return "first"
+
+    def handler2(text: str):
+        return "second"
+
+    router = AgentRouter()
+
+    # Same priority (default 0)
+    router.register("agent1", r"hello", handler1)
+    router.register("agent2", r"hello world", handler2)
+
+    result = await router.route("hello world")
+
+    # Same priority → insertion order preserved
+    assert result == "first"
+
+
+# ---------------------------
+# Higher Priority Wins
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_higher_priority_wins():
+
+    def low_priority(text: str):
+        return "low"
+
+    def high_priority(text: str):
+        return "high"
+
+    router = AgentRouter()
+
+    router.register("low", r"hello", low_priority, priority=1)
+    router.register("high", r"hello world", high_priority, priority=10)
+
+    result = await router.route("hello world")
+
+    assert result == "high"
+
+
+# ---------------------------
+# Multiple Agents Different Patterns
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_multiple_agents():
+
+    def support_handler(text: str):
+        return "support"
+
+    def sales_handler(text: str):
+        return "sales"
+
+    router = AgentRouter()
+
+    router.register("support", r"error|bug", support_handler)
+    router.register("sales", r"price|buy", sales_handler)
+
+    result_support = await router.route("There is a bug")
+    result_sales = await router.route("I want to buy")
+
+    assert result_support == "support"
+    assert result_sales == "sales"
+
+
+# ---------------------------
+# Regex Behavior
+# ---------------------------
+
+@pytest.mark.asyncio
+async def test_regex_matching():
+
+    def handler(text: str):
+        return "matched"
+
+    router = AgentRouter()
+    router.register("test", r"\d+", handler)
+
+    result = await router.route("Order 1234")
+
+    assert result == "matched"