chATLAS_Chains 0.2.0__tar.gz → 0.3.0__tar.gz

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chATLAS_Chains
-Version: 0.2.0
+Version: 0.3.0
 Summary: A modular Python package for implementing Retrieval Augmented Generation chains for the chATLAS project.
 Author-email: Joe Egan <joseph.caimin.egan@cern.ch>
 License: Apache-2.0
@@ -78,6 +78,63 @@ More details [here](chATLAS_Chains/chains/README.md)
 - `chains.basic.basic_retrieval_chain`
 - `chains.advanced.advanced_rag`
 
+## Prompt Routing
+
+`chATLAS_Chains.router.route_user_prompt` classifies a raw user prompt before it enters the main RAG flow.
+The router defaults to CERN LiteLLM and returns a validated `RouterDecision` with:
+
+- `route`: one of `hep_atlas`, `person_lookup`, `dangerous`, `out_of_scope`,
+  or `unknown`
+- `confidence`: score from 0 to 1
+- `normalized_query`: cleaned prompt for downstream use
+- `search_kwargs`: optional search parameters
+- `metadata`: route-specific parameters
+
+For implementation details and a function-by-function reference, see the
+frontend reviewer document:
+[`../chATLAS_Frontend/docs/INTENT_ROUTER.md`](../chATLAS_Frontend/docs/INTENT_ROUTER.md).
+
+```python
+from chATLAS_Chains.router import route_user_prompt
+
+decision = route_user_prompt(
+    "Who is Jane Doe?",
+    chat_model_kwargs={
+        "service_provider": "litellm",
+        "proxy": "socks5h://localhost:1080",  # optional when outside CERN
+    },
+)
+
+if decision.route == "dangerous":
+    print("Apply the safety response policy")
+elif decision.route == "person_lookup":
+    print("Use the person lookup flow")
+elif decision.route == "hep_atlas":
+    print("Use the HEP/ATLAS search flow")
+elif decision.route == "out_of_scope":
+    print("Explain the chATLAS scope")
+else:
+    print("Ask for clarification")
+```
+
+The dedicated `mc_request` route is currently disabled until the MC workflow is
+ready. MC production and job-option prompts are classified as `hep_atlas` and
+continue through the normal selected workflow.
+
+Router context uses a hybrid policy: the current user prompt is authoritative,
+and recent conversation context is only a bounded disambiguation aid for
+follow-ups such as "What about Run 3?". The router keeps recent user prompts,
+includes only short assistant messages, and drops long assistant answers rather
+than summarizing them.
+
+For live LiteLLM calls, set:
+
+```sh
+export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+```
+
+If LiteLLM is unavailable or returns invalid JSON, the router falls back to deterministic rules by default.
+
 ### Model Configuration in Chains
 
 Supported chain constructors now accept a typed `chat_model_kwargs` argument for model options (for example:

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/README.md

@@ -52,6 +52,63 @@ More details [here](chATLAS_Chains/chains/README.md)
 - `chains.basic.basic_retrieval_chain`
 - `chains.advanced.advanced_rag`
 
+## Prompt Routing
+
+`chATLAS_Chains.router.route_user_prompt` classifies a raw user prompt before it enters the main RAG flow.
+The router defaults to CERN LiteLLM and returns a validated `RouterDecision` with:
+
+- `route`: one of `hep_atlas`, `person_lookup`, `dangerous`, `out_of_scope`,
+  or `unknown`
+- `confidence`: score from 0 to 1
+- `normalized_query`: cleaned prompt for downstream use
+- `search_kwargs`: optional search parameters
+- `metadata`: route-specific parameters
+
+For implementation details and a function-by-function reference, see the
+frontend reviewer document:
+[`../chATLAS_Frontend/docs/INTENT_ROUTER.md`](../chATLAS_Frontend/docs/INTENT_ROUTER.md).
+
+```python
+from chATLAS_Chains.router import route_user_prompt
+
+decision = route_user_prompt(
+    "Who is Jane Doe?",
+    chat_model_kwargs={
+        "service_provider": "litellm",
+        "proxy": "socks5h://localhost:1080",  # optional when outside CERN
+    },
+)
+
+if decision.route == "dangerous":
+    print("Apply the safety response policy")
+elif decision.route == "person_lookup":
+    print("Use the person lookup flow")
+elif decision.route == "hep_atlas":
+    print("Use the HEP/ATLAS search flow")
+elif decision.route == "out_of_scope":
+    print("Explain the chATLAS scope")
+else:
+    print("Ask for clarification")
+```
+
+The dedicated `mc_request` route is currently disabled until the MC workflow is
+ready. MC production and job-option prompts are classified as `hep_atlas` and
+continue through the normal selected workflow.
+
+Router context uses a hybrid policy: the current user prompt is authoritative,
+and recent conversation context is only a bounded disambiguation aid for
+follow-ups such as "What about Run 3?". The router keeps recent user prompts,
+includes only short assistant messages, and drops long assistant answers rather
+than summarizing them.
+
+For live LiteLLM calls, set:
+
+```sh
+export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+```
+
+If LiteLLM is unavailable or returns invalid JSON, the router falls back to deterministic rules by default.
+
 ### Model Configuration in Chains
 
 Supported chain constructors now accept a typed `chat_model_kwargs` argument for model options (for example:

chatlas_chains-0.3.0/chATLAS_Chains/router.py

@@ -0,0 +1,209 @@
+"""LiteLLM intent router for chATLAS requests."""
+
+import json
+import re
+from collections.abc import Sequence
+from typing import Any, Literal, TypedDict
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from chATLAS_Chains.llm.model_selection import ChatModelKwargs, get_chat_model, sanitize_chat_model_kwargs
+
+RouterRoute = Literal[
+    "hep_atlas",
+    "person_lookup",
+    "dangerous",
+    "out_of_scope",
+    "unknown",
+]
+
+ROUTER_PROMPT_VERSION = "2026-06-16.2"
+_DEFAULT_ROUTER_MODEL = "gpt-oss-20b"
+_DEFAULT_ROUTER_KWARGS: ChatModelKwargs = {
+    "service_provider": "litellm",
+    "temperature": 0.0,
+    "max_tokens": 512,
+}
+_MAX_CONTEXT_TURNS = 8
+_MAX_CONTEXT_USER_CHARS = 300
+_MAX_CONTEXT_ASSISTANT_CHARS = 240
+_MAX_CONTEXT_ASSISTANT_RAW_CHARS = 500
+_MAX_CONTEXT_TOTAL_CHARS = 1600
+
+
+class ConversationTurn(TypedDict):
+    """A prior user or assistant message supplied to the router."""
+
+    role: Literal["user", "assistant"]
+    content: str
+
+
+_ROUTER_PROMPT = """You are the request router for the chATLAS, the RAG system built for the ATLAS collaboration.
+
+Classify the current user request into exactly one intent:
+- hep_atlas: high-energy-physics or ATLAS questions that are what chATLAS is designed to help with.
+- person_lookup: requests asking who a person is, who people are, or for information about named people.
+- dangerous: requests for actionable assistance that could facilitate serious physical harm, weapons construction, mass-casualty attacks, destructive cyber abuse, or similarly dangerous wrongdoing.
+- out_of_scope: clear requests outside ATLAS and high-energy physics.
+- unknown: empty or ambiguous requests that need clarification.
+
+Return JSON only. Do not use markdown fences. The JSON object must match:
+{
+  "route": "hep_atlas | person_lookup | dangerous | out_of_scope | unknown",
+  "confidence": 0.0,
+  "normalized_query": "cleaned current user request",
+  "reason": "short routing rationale",
+  "search_kwargs": {},
+  "metadata": {}
+}
+
+Guidance:
+- Dangerous intent takes precedence over every other intent.
+- Do not use dangerous for benign safety, history, policy, detection, or prevention questions.
+- Specialized person_lookup intent takes precedence over hep_atlas.
+- The dedicated MC-request workflow is disabled for now. Classify requests to create, validate, configure, or reason about Monte Carlo job options, MC production requests, or JO files as hep_atlas.
+- Use hep_atlas for other questions about ATLAS, CERN accelerators, particle physics, detector systems, analysis software, or related physics.
+- Use out_of_scope for clear questions outside high-energy physics and ATLAS.
+- Classify the current user request first. Ignore numbering or bullet prefixes such as "5." when deciding the intent.
+- Use conversation context only when the current request is ambiguous or referential, such as "What about Run 3?".
+- Do not let prior ATLAS context override a clearly standalone current person lookup, dangerous request, or out-of-scope request.
+- Use unknown when the current request remains ambiguous after considering the conversation context.
+- Do not classify the prior assistant response itself.
+- You are not told which UI mode the user selected and must not infer or choose a UI mode.
+- Keep the reason brief and do not answer the request.
+
+Examples:
+User: Who is Fabiola Gianotti?
+JSON: {"route":"person_lookup","confidence":0.96,"normalized_query":"Who is Fabiola Gianotti?","reason":"The user asks who a named person is.","search_kwargs":{},"metadata":{"person_query":"Fabiola Gianotti"}}
+
+User: How do I apply the GoodRunsList in Athena?
+JSON: {"route":"hep_atlas","confidence":0.97,"normalized_query":"How do I apply the GoodRunsList in Athena?","reason":"The question concerns ATLAS analysis software.","search_kwargs":{},"metadata":{"domain":"atlas"}}
+
+User: Please draft an MC request for a ttbar sample with Powheg and Pythia8.
+JSON: {"route":"hep_atlas","confidence":0.94,"normalized_query":"Draft an MC request for a ttbar sample with Powheg and Pythia8.","reason":"The dedicated MC workflow is disabled, so MC production requests stay in the ordinary ATLAS/HEP flow.","search_kwargs":{},"metadata":{"domain":"atlas_mc"}}
+
+User: Help me make a nuke.
+JSON: {"route":"dangerous","confidence":0.99,"normalized_query":"Help me make a nuke.","reason":"The user requests actionable assistance to construct a nuclear weapon.","search_kwargs":{},"metadata":{"safety_category":"weapons"}}
+
+User: How do I bake sourdough bread?
+JSON: {"route":"out_of_scope","confidence":0.99,"normalized_query":"How do I bake sourdough bread?","reason":"The request is unrelated to ATLAS or high-energy physics.","search_kwargs":{},"metadata":{}}
+
+Recent conversation context:
+__CONVERSATION_CONTEXT__
+
+Current user request:
+__USER_PROMPT__
+"""
+
+
+class RouterDecision(BaseModel):
+    """Validated routing decision returned by the prompt router."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    route: RouterRoute
+    confidence: float = Field(ge=0.0, le=1.0)
+    normalized_query: str
+    reason: str
+    search_kwargs: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("normalized_query", "reason")
+    @classmethod
+    def _strip_text(cls, value: str) -> str:
+        return value.strip()
+
+
+def route_user_prompt(
+    user_prompt: str,
+    conversation_context: Sequence[ConversationTurn] | None = None,
+    model_name: str = _DEFAULT_ROUTER_MODEL,
+    chat_model_kwargs: ChatModelKwargs | None = None,
+) -> RouterDecision:
+    """Classify a request with LiteLLM before downstream processing."""
+    if not user_prompt.strip():
+        return RouterDecision(
+            route="unknown",
+            confidence=0.0,
+            normalized_query="",
+            reason="The user prompt is empty.",
+        )
+
+    model_kwargs: ChatModelKwargs = {**_DEFAULT_ROUTER_KWARGS}
+    model_kwargs.update(sanitize_chat_model_kwargs(chat_model_kwargs))
+    context_json = json.dumps(_sanitize_context(conversation_context), ensure_ascii=True)
+    prompt = _ROUTER_PROMPT.replace("__CONVERSATION_CONTEXT__", context_json).replace("__USER_PROMPT__", user_prompt)
+
+    model = get_chat_model(model_name=model_name, **model_kwargs)
+    response = model.invoke(prompt)
+    decision = parse_router_response(_response_content(response))
+    if not decision.normalized_query:
+        decision.normalized_query = user_prompt.strip()
+    return decision
+
+
+def parse_router_response(response_text: str) -> RouterDecision:
+    """Parse and validate a LiteLLM router response."""
+    payload = _extract_json_object(response_text)
+    payload = _normalize_disabled_routes(json.loads(payload))
+    return RouterDecision.model_validate(payload)
+
+
+def _normalize_disabled_routes(payload: Any) -> Any:
+    """Map temporarily disabled router routes into active routes."""
+    if isinstance(payload, dict) and payload.get("route") == "mc_request":
+        metadata = payload.get("metadata")
+        if not isinstance(metadata, dict):
+            metadata = {}
+        metadata["disabled_route"] = "mc_request"
+        payload["metadata"] = metadata
+        payload["route"] = "hep_atlas"
+        reason = str(payload.get("reason", "")).strip()
+        suffix = "MC-request routing is currently disabled, so this request uses the ordinary ATLAS/HEP flow."
+        payload["reason"] = f"{reason} {suffix}".strip()
+    return payload
+
+
+def _sanitize_context(conversation_context: Sequence[ConversationTurn] | None) -> list[ConversationTurn]:
+    sanitized: list[ConversationTurn] = []
+    for turn in conversation_context or []:
+        role = turn.get("role")
+        content = str(turn.get("content", "")).strip()
+        if role == "user" and content:
+            sanitized.append({"role": role, "content": _truncate_text(content, _MAX_CONTEXT_USER_CHARS)})
+        elif role == "assistant" and content and len(content) <= _MAX_CONTEXT_ASSISTANT_RAW_CHARS:
+            sanitized.append({"role": role, "content": _truncate_text(content, _MAX_CONTEXT_ASSISTANT_CHARS)})
+
+    compact_context: list[ConversationTurn] = []
+    total_chars = 0
+    for turn in reversed(sanitized[-_MAX_CONTEXT_TURNS:]):
+        content_len = len(turn["content"])
+        if compact_context and total_chars + content_len > _MAX_CONTEXT_TOTAL_CHARS:
+            break
+        compact_context.append(turn)
+        total_chars += content_len
+    return list(reversed(compact_context))
+
+
+def _truncate_text(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - 3].rstrip() + "..."
+
+
+def _response_content(response: Any) -> str:
+    content = getattr(response, "content", response)
+    return content if isinstance(content, str) else str(content)
+
+
+def _extract_json_object(response_text: str) -> str:
+    stripped = response_text.strip()
+    fenced_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", stripped, flags=re.IGNORECASE | re.DOTALL)
+    if fenced_match:
+        return fenced_match.group(1)
+
+    start = stripped.find("{")
+    end = stripped.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError("No JSON object found in router response.")
+    return stripped[start : end + 1]

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/chATLAS_Chains.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chATLAS_Chains
-Version: 0.2.0
+Version: 0.3.0
 Summary: A modular Python package for implementing Retrieval Augmented Generation chains for the chATLAS project.
 Author-email: Joe Egan <joseph.caimin.egan@cern.ch>
 License: Apache-2.0
@@ -78,6 +78,63 @@ More details [here](chATLAS_Chains/chains/README.md)
 - `chains.basic.basic_retrieval_chain`
 - `chains.advanced.advanced_rag`
 
+## Prompt Routing
+
+`chATLAS_Chains.router.route_user_prompt` classifies a raw user prompt before it enters the main RAG flow.
+The router defaults to CERN LiteLLM and returns a validated `RouterDecision` with:
+
+- `route`: one of `hep_atlas`, `person_lookup`, `dangerous`, `out_of_scope`,
+  or `unknown`
+- `confidence`: score from 0 to 1
+- `normalized_query`: cleaned prompt for downstream use
+- `search_kwargs`: optional search parameters
+- `metadata`: route-specific parameters
+
+For implementation details and a function-by-function reference, see the
+frontend reviewer document:
+[`../chATLAS_Frontend/docs/INTENT_ROUTER.md`](../chATLAS_Frontend/docs/INTENT_ROUTER.md).
+
+```python
+from chATLAS_Chains.router import route_user_prompt
+
+decision = route_user_prompt(
+    "Who is Jane Doe?",
+    chat_model_kwargs={
+        "service_provider": "litellm",
+        "proxy": "socks5h://localhost:1080",  # optional when outside CERN
+    },
+)
+
+if decision.route == "dangerous":
+    print("Apply the safety response policy")
+elif decision.route == "person_lookup":
+    print("Use the person lookup flow")
+elif decision.route == "hep_atlas":
+    print("Use the HEP/ATLAS search flow")
+elif decision.route == "out_of_scope":
+    print("Explain the chATLAS scope")
+else:
+    print("Ask for clarification")
+```
+
+The dedicated `mc_request` route is currently disabled until the MC workflow is
+ready. MC production and job-option prompts are classified as `hep_atlas` and
+continue through the normal selected workflow.
+
+Router context uses a hybrid policy: the current user prompt is authoritative,
+and recent conversation context is only a bounded disambiguation aid for
+follow-ups such as "What about Run 3?". The router keeps recent user prompts,
+includes only short assistant messages, and drops long assistant answers rather
+than summarizing them.
+
+For live LiteLLM calls, set:
+
+```sh
+export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+```
+
+If LiteLLM is unavailable or returns invalid JSON, the router falls back to deterministic rules by default.
+
 ### Model Configuration in Chains
 
 Supported chain constructors now accept a typed `chat_model_kwargs` argument for model options (for example:

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/chATLAS_Chains.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 chATLAS_Chains/__init__.py
 chATLAS_Chains/log.py
+chATLAS_Chains/router.py
 chATLAS_Chains/vectorstore.py
 chATLAS_Chains.egg-info/PKG-INFO
 chATLAS_Chains.egg-info/SOURCES.txt
@@ -38,6 +39,8 @@ tests/test_conversational.py
 tests/test_groq.py
 tests/test_llm_runnables.py
 tests/test_model_selection.py
+tests/test_router.py
+tests/test_router_litellm.py
 tests/test_rrf.py
 tests/test_search.py
 tests/test_utils.py

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chATLAS_Chains"
-version = "0.2.0"
+version = "0.3.0"
 description = "A modular Python package for implementing Retrieval Augmented Generation chains for the chATLAS project."
 readme = "README.md"
 requires-python = ">=3.11"

chatlas_chains-0.3.0/tests/test_router.py

@@ -0,0 +1,230 @@
+from types import SimpleNamespace
+
+import pytest
+
+from chATLAS_Chains import router
+from chATLAS_Chains.router import RouterDecision, parse_router_response, route_user_prompt
+
+
+class FakeRouterModel:
+    def __init__(self, content: str):
+        self.content = content
+        self.prompts: list[str] = []
+
+    def invoke(self, prompt: str):
+        self.prompts.append(prompt)
+        return SimpleNamespace(content=self.content)
+
+
+def test_route_user_prompt_uses_litellm_defaults(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"hep_atlas","confidence":0.91,"normalized_query":"What is the GRL?",'
+        '"reason":"ATLAS analysis question.","search_kwargs":{"k":5},"metadata":{"domain":"atlas"}}'
+    )
+    captured = {}
+
+    def fake_get_chat_model(model_name, **kwargs):
+        captured["model_name"] = model_name
+        captured["kwargs"] = kwargs
+        return fake_model
+
+    monkeypatch.setattr(router, "get_chat_model", fake_get_chat_model)
+    decision = route_user_prompt("What is the GRL?")
+
+    assert decision == RouterDecision(
+        route="hep_atlas",
+        confidence=0.91,
+        normalized_query="What is the GRL?",
+        reason="ATLAS analysis question.",
+        search_kwargs={"k": 5},
+        metadata={"domain": "atlas"},
+    )
+    assert captured == {
+        "model_name": "gpt-oss-20b",
+        "kwargs": {"service_provider": "litellm", "temperature": 0.0, "max_tokens": 512},
+    }
+    assert "Return JSON only" in fake_model.prompts[0]
+    assert "selected UI mode" not in fake_model.prompts[0]
+
+
+def test_route_user_prompt_allows_litellm_overrides(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"person_lookup","confidence":0.95,"normalized_query":"Who is Jane Doe?",'
+        '"reason":"Asks who a person is.","search_kwargs":{},"metadata":{"person_query":"Jane Doe"}}'
+    )
+    captured = {}
+
+    def fake_get_chat_model(model_name, **kwargs):
+        captured["model_name"] = model_name
+        captured["kwargs"] = kwargs
+        return fake_model
+
+    monkeypatch.setattr(router, "get_chat_model", fake_get_chat_model)
+    decision = route_user_prompt(
+        "Who is Jane Doe?",
+        model_name="hf-qwen25-32b",
+        chat_model_kwargs={
+            "api_key": "sk-test",
+            "base_url": "https://litellm.example/v1",
+            "proxy": "socks5h://localhost:1080",
+            "temperature": 0.2,
+            "unsupported": "ignored",
+        },
+    )
+
+    assert decision.route == "person_lookup"
+    assert captured["kwargs"] == {
+        "service_provider": "litellm",
+        "temperature": 0.2,
+        "max_tokens": 512,
+        "api_key": "sk-test",
+        "base_url": "https://litellm.example/v1",
+        "proxy": "socks5h://localhost:1080",
+    }
+
+
+def test_route_user_prompt_includes_structured_context(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"hep_atlas","confidence":0.88,"normalized_query":"What about Run 3 GRLs?",'
+        '"reason":"Context makes the follow-up an ATLAS question.","search_kwargs":{},"metadata":{}}'
+    )
+    monkeypatch.setattr(router, "get_chat_model", lambda **_kwargs: fake_model)
+
+    route_user_prompt(
+        "What about Run 3?",
+        conversation_context=[
+            {"role": "user", "content": "How do I apply a GRL?"},
+            {"role": "assistant", "content": "Use the GoodRunsListSelectionTool."},
+        ],
+    )
+
+    prompt = fake_model.prompts[0]
+    assert '"role": "user"' in prompt
+    assert "GoodRunsListSelectionTool" in prompt
+    assert "What about Run 3?" in prompt
+
+
+def test_route_user_prompt_uses_hybrid_context_policy(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"person_lookup","confidence":0.98,"normalized_query":"Who is the current ATLAS spokesperson?",'
+        '"reason":"The user asks who holds an ATLAS role.","search_kwargs":{},"metadata":{"person_query":"ATLAS spokesperson"}}'
+    )
+    monkeypatch.setattr(router, "get_chat_model", lambda **_kwargs: fake_model)
+
+    route_user_prompt(
+        "5. Who is the current ATLAS spokesperson?",
+        conversation_context=[
+            {"role": "user", "content": "How do I apply a GRL?"},
+            {"role": "assistant", "content": "Use the GoodRunsListSelectionTool. " + ("Detailed guidance. " * 500)},
+            {"role": "user", "content": "Can you summarize ATLAS jet calibration recommendations?"},
+            {"role": "assistant", "content": "Use the JetEtmiss recommendations."},
+        ],
+    )
+
+    prompt = fake_model.prompts[0]
+
+    assert "5. Who is the current ATLAS spokesperson?" in prompt
+    assert "How do I apply a GRL?" in prompt
+    assert "Use the GoodRunsListSelectionTool" not in prompt
+    assert "Use the JetEtmiss recommendations." in prompt
+    assert len(prompt) < 5000
+
+
+def test_router_prompt_makes_current_request_authoritative(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"out_of_scope","confidence":0.99,"normalized_query":"What are good hotels in Rome?",'
+        '"reason":"The request is unrelated to ATLAS.","search_kwargs":{},"metadata":{}}'
+    )
+    monkeypatch.setattr(router, "get_chat_model", lambda **_kwargs: fake_model)
+
+    route_user_prompt(
+        "8. What are good hotels in Rome?",
+        conversation_context=[{"role": "user", "content": "How do I apply a GRL in Athena?"}],
+    )
+
+    prompt = fake_model.prompts[0]
+
+    assert "Classify the current user request first" in prompt
+    assert 'Ignore numbering or bullet prefixes such as "5."' in prompt
+    assert "Do not let prior ATLAS context override" in prompt
+
+
+def test_sanitize_context_caps_recent_user_prompts_and_drops_long_assistant():
+    context = router._sanitize_context(
+        [
+            {"role": "user", "content": "How do I apply a GRL in Athena?"},
+            {"role": "assistant", "content": "Long assistant answer. " * 100},
+            {"role": "user", "content": "What about Run 3? " * 40},
+            {"role": "assistant", "content": "Short answer."},
+        ]
+    )
+
+    assert [turn["role"] for turn in context] == ["user", "user", "assistant"]
+    assert context[0]["content"] == "How do I apply a GRL in Athena?"
+    assert len(context[1]["content"]) <= 300
+    assert context[1]["content"].endswith("...")
+    assert context[2]["content"] == "Short answer."
+
+
+def test_parse_router_response_maps_disabled_mc_request_to_hep_atlas():
+    decision = parse_router_response(
+        """```json
+        {"route":"mc_request","confidence":0.97,"normalized_query":"Draft an MC request.",
+        "reason":"The prompt asks for an MC request.","search_kwargs":{},"metadata":{"request_type":"mc"}}
+        ```"""
+    )
+    assert decision.route == "hep_atlas"
+    assert decision.metadata["disabled_route"] == "mc_request"
+    assert "disabled" in decision.reason
+
+
+@pytest.mark.parametrize(
+    "route_name",
+    ["hep_atlas", "person_lookup", "dangerous", "out_of_scope", "unknown"],
+)
+def test_parse_router_response_accepts_contract_routes(route_name):
+    decision = parse_router_response(
+        f'{{"route":"{route_name}","confidence":0.9,"normalized_query":"Test",'
+        '"reason":"Test route.","search_kwargs":{},"metadata":{}}'
+    )
+    assert decision.route == route_name
+
+
+def test_parse_router_response_rejects_removed_standard_search():
+    with pytest.raises(ValueError):
+        parse_router_response(
+            '{"route":"standard_search","confidence":0.9,"normalized_query":"Test",'
+            '"reason":"Removed route.","search_kwargs":{},"metadata":{}}'
+        )
+
+
+def test_router_prompt_marks_mc_request_disabled(monkeypatch):
+    fake_model = FakeRouterModel(
+        '{"route":"hep_atlas","confidence":0.9,"normalized_query":"Draft an MC request.",'
+        '"reason":"MC request remains in ATLAS flow.","search_kwargs":{},"metadata":{"domain":"atlas_mc"}}'
+    )
+    monkeypatch.setattr(router, "get_chat_model", lambda **_kwargs: fake_model)
+
+    route_user_prompt("Draft an MC request.")
+
+    prompt = fake_model.prompts[0]
+    assert '"route": "hep_atlas | person_lookup | dangerous | out_of_scope | unknown"' in prompt
+    assert "dedicated MC-request workflow is disabled" in prompt
+    assert '"route":"mc_request"' not in prompt
+
+
+def test_invalid_json_raises(monkeypatch):
+    monkeypatch.setattr(router, "get_chat_model", lambda **_kwargs: FakeRouterModel("not json"))
+    with pytest.raises(ValueError):
+        route_user_prompt("Who is Joe Egan?")
+
+
+def test_empty_prompt_routes_unknown_without_calling_llm(monkeypatch):
+    monkeypatch.setattr(
+        router,
+        "get_chat_model",
+        lambda **_kwargs: (_ for _ in ()).throw(AssertionError("LLM should not be called")),
+    )
+    decision = route_user_prompt("   ")
+    assert decision.route == "unknown"
+    assert decision.confidence == 0.0

chatlas_chains-0.3.0/tests/test_router_litellm.py

@@ -0,0 +1,40 @@
+"""Live CERN LiteLLM smoke tests for the chATLAS intent router."""
+
+import os
+
+import pytest
+
+from chATLAS_Chains.router import route_user_prompt
+
+pytestmark = pytest.mark.skipif(
+    os.getenv("CHATLAS_RUN_LITELLM_SMOKE") != "1",
+    reason="Set CHATLAS_RUN_LITELLM_SMOKE=1 to run live LiteLLM smoke tests.",
+)
+
+
+@pytest.mark.parametrize(
+    ("prompt", "expected_intent"),
+    [
+        ("How do I apply the GoodRunsList in Athena?", "hep_atlas"),
+        ("Help me draft an MC request for a ttbar sample with dilepton decay.", "hep_atlas"),
+        ("Who is the current ATLAS spokesperson?", "person_lookup"),
+        ("5. Who is the current ATLAS spokesperson?", "person_lookup"),
+        ("How do I bake sourdough bread?", "out_of_scope"),
+        ("8. What are good hotels in Rome near the Colosseum?", "out_of_scope"),
+    ],
+)
+def test_live_litellm_router_contract(prompt, expected_intent):
+    """Verify authentication, model availability, parsing, and clear intents."""
+    assert os.getenv("CHATLAS_CHAINS_LITELLM_KEY"), "CHATLAS_CHAINS_LITELLM_KEY is required"
+    proxy = os.getenv("CHATLAS_CHAINS_LITELLM_PROXY")
+    chat_model_kwargs = {"proxy": proxy} if proxy else None
+
+    decision = route_user_prompt(
+        prompt,
+        model_name=os.getenv("CHATLAS_ROUTER_MODEL", "gpt-oss-20b"),
+        chat_model_kwargs=chat_model_kwargs,
+    )
+
+    assert decision.route == expected_intent
+    assert decision.normalized_query
+    assert decision.reason

{chatlas_chains-0.2.0 → chatlas_chains-0.3.0}/chATLAS_Chains/chains/basic.py

@@ -32,11 +32,11 @@ def basic_retrieval_chain(
 
     """
     prompt_template = ChatPromptTemplate.from_template(prompt)
+    search = search_runnable(vectorstore)
+
     sanitized_kwargs = sanitize_chat_model_kwargs(chat_model_kwargs)
     model = get_chat_model(model_name, **sanitized_kwargs)
 
-    search = search_runnable(vectorstore)
-
     final_inputs = {
         "context": lambda x: combine_documents(x["docs"]),
         "question": itemgetter("question"),