New features: Route Stickness, Handoff, Clarification, Read-Only/Transactional, Long Term Memory

tests/unit/test_semantic_route_stickiness.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from agent_framework.routing.continuity import SemanticRouteContinuity
+from agent_framework.routing.models import IntentDefinition
+
+
+class FakeLLM:
+    def __init__(self, response: dict | str):
+        self.response = response
+        self.calls = []
+
+    async def ainvoke(self, messages, **kwargs):
+        self.calls.append((messages, kwargs))
+        if isinstance(self.response, str):
+            return self.response
+        return json.dumps(self.response)
+
+
+class FakeTelemetry:
+    def __init__(self):
+        self.events = []
+
+    async def event(self, name, payload):
+        self.events.append((name, payload))
+
+
+def settings(**overrides):
+    values = {
+        "ENABLE_ROUTE_STICKINESS": True,
+        "ROUTE_STICKINESS_LLM_PROFILE": "route_continuity",
+        "ROUTE_STICKINESS_CONFIDENCE_THRESHOLD": 0.90,
+        "ROUTE_STICKINESS_HISTORY_TURNS": 2,
+        "ROUTE_STICKINESS_MAX_TOKENS": 80,
+    }
+    values.update(overrides)
+    return SimpleNamespace(**values)
+
+
+def intents():
+    return [
+        IntentDefinition(
+            name="product_services_information",
+            agent="product_agent",
+            description="Planos, serviços, benefícios e mudança de plano.",
+        ),
+        IntentDefinition(
+            name="billing_invoice_explanation",
+            agent="billing_agent",
+            description="Faturas, pagamentos, cobranças e contestação.",
+        ),
+    ]
+
+
+def state(message="o que está incluso?"):
+    return {
+        "session_id": "s1",
+        "active_agent": "product_agent",
+        "intent": "product_services_information",
+        "domain": "telecom",
+        "route_decision": {
+            "intent": "product_services_information",
+            "domain": "telecom",
+            "mcp_tools": ["consultar_plano"],
+        },
+        "history": [
+            {"role": "user", "content": "qual é o meu plano?"},
+            {"role": "assistant", "content": "Seu plano atual é Controle 50GB."},
+        ],
+        "user_text": message,
+        "sanitized_input": message,
+    }
+
+
+@pytest.mark.asyncio
+async def test_continue_bypasses_router_without_regex_rules():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.97, "reason": "Continua o assunto do plano."})
+    telemetry = FakeTelemetry()
+    policy = SemanticRouteContinuity(settings(), llm, telemetry)
+
+    decision = await policy.evaluate(state(), intents=intents())
+
+    assert decision is not None
+    assert decision.agent == "product_agent"
+    assert decision.method == "continuity"
+    assert decision.metadata["route_bypassed"] is True
+    assert llm.calls[0][1]["profile_name"] == "route_continuity"
+    prompt = json.loads(llm.calls[0][0][1]["content"])
+    assert prompt["current_message"] == "o que está incluso?"
+    assert "product_agent" not in prompt["other_agents"]
+    assert telemetry.events[-1][1]["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_route_result_falls_back_to_enterprise_router():
+    llm = FakeLLM({"decision": "ROUTE", "confidence": 0.98, "reason": "Novo assunto de cobrança."})
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(
+        state("agora quero contestar uma cobrança"), intents=intents()
+    )
+
+    assert decision is None
+
+
+@pytest.mark.asyncio
+async def test_low_confidence_continue_falls_back_safely():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.70, "reason": "Possível continuidade."})
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    assert await policy.evaluate(state(), intents=intents()) is None
+
+
+@pytest.mark.asyncio
+async def test_invalid_output_falls_back_safely():
+    llm = FakeLLM("not-json")
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    assert await policy.evaluate(state(), intents=intents()) is None
+
+
+@pytest.mark.asyncio
+async def test_no_active_agent_still_classifies_global_session_actions():
+    llm = FakeLLM({"decision": "ROUTE", "confidence": 1.0})
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state()
+    current.pop("active_agent")
+
+    assert await policy.evaluate(current, intents=intents()) is None
+    assert len(llm.calls) == 1
+
+@pytest.mark.asyncio
+async def test_human_handoff_is_returned_as_global_route():
+    llm = FakeLLM({
+        "decision": "HUMAN_HANDOFF",
+        "confidence": 0.99,
+        "reason": "O usuário pediu atendimento humano.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(
+        state("quero falar com um atendente"), intents=intents()
+    )
+
+    assert decision is not None
+    assert decision.route == "human_handoff"
+    assert decision.agent == "human_handoff"
+    assert decision.intent == "human_handoff"
+    assert decision.handoff is True
+    assert decision.metadata["session_control"] == "HUMAN_HANDOFF"
+    assert decision.metadata["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_end_session_is_returned_as_global_route():
+    llm = FakeLLM({
+        "decision": "END_SESSION",
+        "confidence": 0.98,
+        "reason": "O usuário informou que não precisa continuar.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+
+    decision = await policy.evaluate(state("obrigado, era só isso"), intents=intents())
+
+    assert decision is not None
+    assert decision.route == "end_session"
+    assert decision.agent == "end_session"
+    assert decision.intent == "end_session"
+    assert decision.handoff is False
+    assert decision.metadata["session_control"] == "END_SESSION"
+    assert decision.metadata["route_bypassed"] is True
+
+
+@pytest.mark.asyncio
+async def test_global_session_actions_work_without_active_agent():
+    llm = FakeLLM({
+        "decision": "HUMAN_HANDOFF",
+        "confidence": 0.97,
+        "reason": "Solicitação explícita de pessoa.",
+    })
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state("quero uma pessoa")
+    current.pop("active_agent")
+
+    decision = await policy.evaluate(current, intents=intents())
+
+    assert decision is not None
+    assert decision.route == "human_handoff"
+    assert len(llm.calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_continue_without_active_agent_falls_back_to_router():
+    llm = FakeLLM({"decision": "CONTINUE", "confidence": 0.99})
+    policy = SemanticRouteContinuity(settings(), llm)
+    current = state()
+    current.pop("active_agent")
+
+    assert await policy.evaluate(current, intents=intents()) is None
+    assert len(llm.calls) == 1

tests/unit/test_tool_policies.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from agent_framework.mcp.tool_policy import ToolPolicyRegistry
+from agent_framework.mcp.tool_router import MCPToolRouter
+
+
+class _Registry:
+    def __init__(self, tool=None):
+        self.tool = tool
+
+    def get_tool(self, _name):
+        return self.tool
+
+
+def _router(policy_registry, legacy=None):
+    router = MCPToolRouter.__new__(MCPToolRouter)
+    router.tool_policies = policy_registry
+    router.registry = _Registry(legacy)
+    return router
+
+
+def test_missing_policy_file_preserves_legacy_behavior(tmp_path):
+    policies = ToolPolicyRegistry(str(tmp_path / "missing.yaml"))
+    legacy = SimpleNamespace(
+        tool_type="action",
+        requires=["order_id"],
+        confirmation_required=True,
+        execution_policy={},
+    )
+    router = _router(policies, legacy)
+
+    allowed, reason, metadata = router.validate_execution_policy("alterar", {"order_id": "42"})
+
+    assert allowed is False
+    assert "confirmação" in reason
+    assert metadata["operation_type"] == "transactional"
+    assert metadata["policy_source"] == "tools.yaml"
+
+
+def test_read_only_policy_executes_without_confirmation(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  consultar:\n    operation_type: read_only\n",
+        encoding="utf-8",
+    )
+    router = _router(ToolPolicyRegistry(str(path)))
+
+    allowed, reason, metadata = router.validate_execution_policy("consultar", {})
+
+    assert allowed is True
+    assert reason is None
+    assert metadata["operation_type"] == "read_only"
+
+
+def test_transactional_policy_requires_literal_boolean_confirmation(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  cancelar:\n    operation_type: transactional\n    require_confirmation: true\n",
+        encoding="utf-8",
+    )
+    router = _router(ToolPolicyRegistry(str(path)))
+
+    denied, _, _ = router.validate_execution_policy("cancelar", {"confirmed": "true"})
+    allowed, reason, metadata = router.validate_execution_policy("cancelar", {"confirmed": True})
+
+    assert denied is False
+    assert allowed is True
+    assert reason is None
+    assert metadata["policy_source"] == "tool_policies.yaml"
+
+
+def test_requires_confirmation_alias_is_supported(tmp_path):
+    path = tmp_path / "tool_policies.yaml"
+    path.write_text(
+        "tool_policies:\n  alterar:\n    type: transactional\n    requires_confirmation: true\n",
+        encoding="utf-8",
+    )
+
+    policy = ToolPolicyRegistry(str(path)).get("alterar")
+
+    assert policy.operation_type == "transactional"
+    assert policy.require_confirmation is True