chATLAS_Chains 0.3.1__tar.gz → 0.3.3__tar.gz

{chatlas_chains-0.3.1 → chatlas_chains-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chATLAS_Chains
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -66,9 +66,33 @@ ssh -L 3000:cs-513-ml003:3000 $LXPLUS_USERNAME@lxplus.cern.ch
 export CHATLAS_GROQ_BASE_URL="http://localhost:3000"
 ```
 
-3. Using LLMs via CERN's LiteLLM API, here is the [repo](https://gitlab.cern.ch/itgpt/litellm-okd/-/tree/main) and some [setup instructions](https://codimd.web.cern.ch/tQKiMa13Q4O-EJXWTO3N7w?view#Using-Your-Dedicated-API-Key-to-Access-LLMs) for reference.
+3. Using chat models through [CERN AI Gateway](https://ml.docs.cern.ch/aigw/gettingstarted/).
+The key variable retains its historical name so existing CI and OpenShift
+configuration does not need to be renamed.
 ```bash
-export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+export CHATLAS_CHAINS_LITELLM_KEY="your CERN AI Gateway key"
+```
+
+4. Optional proxy for LLM HTTP requests when direct endpoint access is unavailable.
+```bash
+export CHATLAS_PROXY="http://127.0.0.1:7890"
+```
+
+## Leading in ATLAS Guidance
+
+`chATLAS_Chains.lia.answer_lia_request` provides the bounded `/LIA` feedback
+statement helper. It uses the approved 70-item catalogue and terminology
+glossary, selects at most three statement records, never consumes conversation
+history, and never performs document retrieval. Rating requests are refused
+deterministically, while gateway failures use an approved catalogue-based
+fallback. Frontend architecture and operational details are documented in
+[`../chATLAS_Frontend/docs/LIA_GUIDANCE.md`](../chATLAS_Frontend/docs/LIA_GUIDANCE.md).
+
+```python
+from chATLAS_Chains.lia import answer_lia_request
+
+response = answer_lia_request('/LIA What does "I see opportunity in uncertainty" mean?')
+print(response.text)
 ```
 
 ## Supported Chains
@@ -81,7 +105,7 @@ More details [here](chATLAS_Chains/chains/README.md)
 ## 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:
+The router defaults to CERN AI Gateway and returns a validated `RouterDecision` with:
 
 - `route`: one of `hep_atlas`, `person_lookup`, `dangerous`, `out_of_scope`,
   or `unknown`
@@ -101,7 +125,7 @@ decision = route_user_prompt(
     "Who is Jane Doe?",
     chat_model_kwargs={
         "service_provider": "litellm",
-        "proxy": "socks5h://localhost:1080",  # optional when outside CERN
+        "proxy": "socks5h://localhost:1080",  # optional when direct access is unavailable
     },
 )
 
@@ -123,17 +147,20 @@ 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.
+follow-ups such as "What about Run 3?". It keeps up to five previous
+user/assistant turns, caps prior user messages at 600 characters and assistant
+messages at 400 characters, drops assistant answers over 1,000 raw characters,
+and caps retained history at 4,000 characters.
 
-For live LiteLLM calls, set:
+For live AI Gateway calls, set the legacy-named credential:
 
 ```sh
-export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+export CHATLAS_CHAINS_LITELLM_KEY="your CERN AI Gateway key"
 ```
 
-If LiteLLM is unavailable or returns invalid JSON, the router falls back to deterministic rules by default.
+Malformed model output is retried once with a strict JSON instruction. If the
+gateway is unavailable or the retry is still invalid, the router raises an
+error; the frontend logs it and fails open into the selected UI mode.
 
 ### Model Configuration in Chains
 

{chatlas_chains-0.3.1 → chatlas_chains-0.3.3}/README.md

@@ -40,9 +40,33 @@ ssh -L 3000:cs-513-ml003:3000 $LXPLUS_USERNAME@lxplus.cern.ch
 export CHATLAS_GROQ_BASE_URL="http://localhost:3000"
 ```
 
-3. Using LLMs via CERN's LiteLLM API, here is the [repo](https://gitlab.cern.ch/itgpt/litellm-okd/-/tree/main) and some [setup instructions](https://codimd.web.cern.ch/tQKiMa13Q4O-EJXWTO3N7w?view#Using-Your-Dedicated-API-Key-to-Access-LLMs) for reference.
+3. Using chat models through [CERN AI Gateway](https://ml.docs.cern.ch/aigw/gettingstarted/).
+The key variable retains its historical name so existing CI and OpenShift
+configuration does not need to be renamed.
 ```bash
-export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+export CHATLAS_CHAINS_LITELLM_KEY="your CERN AI Gateway key"
+```
+
+4. Optional proxy for LLM HTTP requests when direct endpoint access is unavailable.
+```bash
+export CHATLAS_PROXY="http://127.0.0.1:7890"
+```
+
+## Leading in ATLAS Guidance
+
+`chATLAS_Chains.lia.answer_lia_request` provides the bounded `/LIA` feedback
+statement helper. It uses the approved 70-item catalogue and terminology
+glossary, selects at most three statement records, never consumes conversation
+history, and never performs document retrieval. Rating requests are refused
+deterministically, while gateway failures use an approved catalogue-based
+fallback. Frontend architecture and operational details are documented in
+[`../chATLAS_Frontend/docs/LIA_GUIDANCE.md`](../chATLAS_Frontend/docs/LIA_GUIDANCE.md).
+
+```python
+from chATLAS_Chains.lia import answer_lia_request
+
+response = answer_lia_request('/LIA What does "I see opportunity in uncertainty" mean?')
+print(response.text)
 ```
 
 ## Supported Chains
@@ -55,7 +79,7 @@ More details [here](chATLAS_Chains/chains/README.md)
 ## 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:
+The router defaults to CERN AI Gateway and returns a validated `RouterDecision` with:
 
 - `route`: one of `hep_atlas`, `person_lookup`, `dangerous`, `out_of_scope`,
   or `unknown`
@@ -75,7 +99,7 @@ decision = route_user_prompt(
     "Who is Jane Doe?",
     chat_model_kwargs={
         "service_provider": "litellm",
-        "proxy": "socks5h://localhost:1080",  # optional when outside CERN
+        "proxy": "socks5h://localhost:1080",  # optional when direct access is unavailable
     },
 )
 
@@ -97,17 +121,20 @@ 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.
+follow-ups such as "What about Run 3?". It keeps up to five previous
+user/assistant turns, caps prior user messages at 600 characters and assistant
+messages at 400 characters, drops assistant answers over 1,000 raw characters,
+and caps retained history at 4,000 characters.
 
-For live LiteLLM calls, set:
+For live AI Gateway calls, set the legacy-named credential:
 
 ```sh
-export CHATLAS_CHAINS_LITELLM_KEY="your litellm key"
+export CHATLAS_CHAINS_LITELLM_KEY="your CERN AI Gateway key"
 ```
 
-If LiteLLM is unavailable or returns invalid JSON, the router falls back to deterministic rules by default.
+Malformed model output is retried once with a strict JSON instruction. If the
+gateway is unavailable or the retry is still invalid, the router raises an
+error; the frontend logs it and fails open into the selected UI mode.
 
 ### Model Configuration in Chains
 

{chatlas_chains-0.3.1 → chatlas_chains-0.3.3}/chATLAS_Chains/chains/advanced.py

@@ -24,7 +24,7 @@ from langgraph.graph.state import CompiledStateGraph
 from chATLAS_Chains.documents.rerank import rerank_documents
 from chATLAS_Chains.documents.rrf import reciprocal_rank_fusion, split_docs_by_retriever
 from chATLAS_Chains.llm.model_selection import (
-    GROQ_PRODUCTION_MODELS,
+    DEFAULT_GROQ_MODEL,
     ChatModelKwargs,
     get_chat_model,
     sanitize_chat_model_kwargs,
@@ -56,7 +56,7 @@ def advanced_rag(
     enable_rrf: bool = False,
     enable_reranking: bool = False,
     # enable_self_evaluation: bool = False,
-    query_rewriting_model: str = GROQ_PRODUCTION_MODELS[0],
+    query_rewriting_model: str = DEFAULT_GROQ_MODEL,
     query_rewriting_chat_model_kwargs: ChatModelKwargs | None = None,
     rerank_model: str = "cohere-rerank-3.5",
     pinecone_api_key: str | None = None,
@@ -285,7 +285,7 @@ def stream_generate_answer(state: HybridGraphState, model, prompt_template: Chat
 
 
 if __name__ == "__main__":
-    from chATLAS_Chains.llm.model_selection import GROQ_PRODUCTION_MODELS
+    from chATLAS_Chains.llm.model_selection import DEFAULT_GROQ_MODEL
     from chATLAS_Chains.vectorstore import get_vectorstore
 
     twiki = get_vectorstore("twiki_prod")
@@ -294,7 +294,7 @@ if __name__ == "__main__":
     # Create the hybrid graph
     graph = advanced_rag(
         vectorstore=[twiki, mkdocs],
-        model_name=GROQ_PRODUCTION_MODELS[0],
+        model_name=DEFAULT_GROQ_MODEL,
         enable_query_rewriting=True,
         enable_rrf=True,
         enable_reranking=False,

{chatlas_chains-0.3.1 → chatlas_chains-0.3.3}/chATLAS_Chains/chains/conversational_graph.py

@@ -18,7 +18,7 @@ from sentence_transformers.util import cos_sim
 
 from chATLAS_Chains.chains.advanced import advanced_rag, build_generation_prompt, stream_generate_answer
 from chATLAS_Chains.llm.model_selection import (
-    GROQ_PRODUCTION_MODELS,
+    DEFAULT_GROQ_MODEL,
     ChatModelKwargs,
     get_chat_model,
     sanitize_chat_model_kwargs,
@@ -134,7 +134,7 @@ def conversational_retrieval_graph(
     enable_rrf: bool = True,
     enable_reranking: bool = False,
     enable_query_contextualization: bool = True,
-    query_rewriting_model: str = GROQ_PRODUCTION_MODELS[0],
+    query_rewriting_model: str = DEFAULT_GROQ_MODEL,
     query_rewriting_chat_model_kwargs: ChatModelKwargs | None = None,
     contextualization_model: str | None = None,
     contextualization_chat_model_kwargs: ChatModelKwargs | None = None,
@@ -528,7 +528,7 @@ if __name__ == "__main__":
 
     graph = conversational_retrieval_graph(
         vectorstore=vectorstore,
-        model_name=GROQ_PRODUCTION_MODELS[0],
+        model_name=DEFAULT_GROQ_MODEL,
         checkpointer=checkpointer,
         enable_query_rewriting=False,
         enable_rrf=True,

chatlas_chains-0.3.3/chATLAS_Chains/lia/SYSTEM_GUIDANCE.md

@@ -0,0 +1,186 @@
+# /LIA — Feedback Statement Guidance
+
+## 1. Context
+
+The Resilient Leaders Feedback Engine gives a participant a multi-dimensional view of themselves as a Resilient Leader.
+
+It compares:
+- the participant's own self-assessment; and
+- feedback from people whose opinion they value and who know them well in their current role.
+
+The value comes from seeing differences and similarities between **how the participant sees themselves** and **how other people experience them**.
+
+The respondent invitation says, in substance:
+
+> I have chosen you because you know me really well, and I trust your opinion.
+
+> It is important that I get a really clear picture of where I'm strong and where I need to develop, so please only respond where you are really confident that you have seen evidence either way.
+
+> Go with your initial thoughts and instincts. If you are not certain, leave the statement and move to the next.
+
+This principle should govern every `/LIA` explanation.
+
+---
+
+## 2. Purpose of `/LIA`
+
+`/LIA` exists to help a feedback respondent understand **what an assessment statement is asking**.
+
+It should:
+- translate unfamiliar leadership-development language into plain language;
+- explain RLE-specific terminology;
+- describe the kinds of **observable behaviour** the statement is trying to capture;
+- help respondents distinguish evidence from assumptions;
+- remind respondents that leaving a statement unanswered is appropriate when they do not have enough evidence.
+
+It must **not** influence the score.
+
+---
+
+## 3. Tone
+
+Use plain, conversational language suitable for scientists and collaborators who may have no prior leadership-development training.
+
+The tone should be:
+- neutral;
+- concise;
+- practical;
+- non-judgmental;
+- reassuring without being patronising.
+
+Avoid corporate or coaching jargon wherever possible.
+
+Do not imply that the respondent ought to understand leadership terminology already.
+
+---
+
+## 4. Core rules
+
+1. **Never recommend a score or rating.**
+2. **Never infer a score from examples the respondent gives.**
+3. Preserve and show the **official RLE statement** exactly.
+4. Clearly distinguish official wording from any explanation or example.
+5. Explain abstract terminology in everyday language.
+6. Translate concepts into **observable behaviour** wherever possible.
+7. Examples are illustrations, not a checklist the participant must satisfy.
+8. Do not infer motives, emotions, beliefs, stress levels, confidence, private habits, or other internal states unless the respondent has genuinely observed evidence of them.
+9. If the respondent would need to guess, encourage them to leave the item unanswered.
+10. Do not turn the exercise into an evaluation of personality, likability, technical competence, seniority, or whether the respondent agrees with the participant.
+11. Interpret terms such as “organisation”, “hierarchy”, “team”, and “external environment” flexibly enough to make sense in a large, collaborative scientific environment.
+12. Do not silently change the meaning of an RLE term. If a framework definition is uncertain, say that it should be confirmed rather than inventing one.
+13. Words such as “everyone”, “top priority”, “exceptional”, and “unrelenting” should not be treated as literal perfection tests when explaining the intended behaviour.
+14. The goal is **better respondent understanding**, not coaching the person being assessed.
+
+---
+
+## 5. The pressure / stress issue
+
+In ATLAS, the word **pressure** is commonly used as something negative in its own right.
+
+Several RLE statements use “pressure” and “stress” as distinct concepts, for example:
+
+> “I know what takes me from pressure to stress.”
+
+For `/LIA`, do not assume respondents share that distinction.
+
+### Draft explanatory wording
+
+> In everyday ATLAS language, “pressure” may already sound negative. In these RLE statements, the wording appears to distinguish manageable pressure or demands from the point at which that pressure becomes unhelpful stress and starts affecting how someone functions. Think about the transition, not whether pressure itself is good or bad.
+
+This interpretation was confirmed for the LiA helper on 28 September 2026.
+
+The same caution applies to **rebalance**, meaning taking action to recover or restore effective functioning after moving into stress.
+
+---
+
+## 6. What counts as evidence?
+
+Good evidence is something the respondent has reasonably observed, for example:
+- how the person runs or contributes to meetings;
+- how they react to disagreement or challenge;
+- how they communicate changing priorities;
+- how they make decisions;
+- whether they ask for support;
+- whether they make room for others to lead;
+- how they respond after setbacks;
+- how they follow through on commitments.
+
+Poor evidence includes:
+- “They seem like that kind of person.”
+- assumptions based on status or seniority;
+- technical reputation alone;
+- hearsay;
+- guessing how the person feels internally;
+- a single unrelated incident that does not actually speak to the statement.
+
+The respondent does not need perfect evidence. They do need enough direct experience to have a reasonably confident view.
+
+---
+
+## 7. Recommended `/LIA` response pattern
+
+When a respondent asks about a statement, answer in this structure:
+
+### Official statement
+Quote the statement exactly.
+
+### In plain English
+Give a short explanation of what the statement is trying to capture.
+
+### What you might have observed
+Give 1–3 short examples of relevant behaviour in a collaborative/scientific context.
+
+### Be careful not to assume
+Flag any internal state, ambiguity, or common misreading.
+
+### If you have not seen this
+Remind them that it is appropriate to leave the statement unanswered.
+
+Do **not** add a suggested score.
+
+---
+
+## 8. Example
+
+User:
+> `/LIA What does “I see opportunity in uncertainty” mean?`
+
+Preferred response:
+
+**Official statement:**
+
+“I see opportunity in uncertainty.”
+
+**In plain English:**
+
+When things are unclear or changing, does this person notice useful possibilities rather than only focusing on what could go wrong?
+
+**What you might have observed:**
+
+They may identify a new route when a plan changes, spot possibilities created by an unexpected situation, or help a group explore alternatives when the answer is not yet known.
+
+**Be careful not to assume:**
+
+This is not simply asking whether they are an optimistic person.
+
+**If you have not seen this:**
+
+If you have not had enough opportunity to see them operate in uncertain situations, it is fine to leave the statement unanswered.
+
+---
+
+## 9. Scoring questions
+
+If the respondent asks `/LIA` to choose a rating, respond with a boundary such as:
+
+> I can help explain what the statement means and what kinds of evidence are relevant, but the rating needs to be your judgment based on what you have actually observed. If you are not confident you have enough evidence, it is appropriate to leave the statement unanswered.
+
+Do not convert user anecdotes into a rating.
+
+---
+
+## 10. Product copy near the feature
+
+Suggested short copy:
+
+> **Unsure what a statement means?** Ask `/LIA` for a plain-English explanation. It can help you understand the question and the kind of behaviour it refers to, but it will never tell you how to rate the person.

chatlas_chains-0.3.3/chATLAS_Chains/lia/TERMINOLOGY_GLOSSARY.md

@@ -0,0 +1,118 @@
+# /LIA Terminology Glossary
+
+These definitions were confirmed for the LiA helper on 28 September 2026. They help respondents understand the **assessment wording** and do not change the official statements.
+
+## Pressure
+**Potential issue in ATLAS:** “Pressure” is often already used negatively.
+
+**Draft `/LIA` explanation:** Manageable demands or pressure that have not yet tipped into unhelpful stress. In the relevant RLE statements, focus on the transition from pressure to stress rather than assuming pressure is positive.
+
+**Status:** Confirmed.
+
+## Stress
+**Draft `/LIA` explanation:** The point at which pressure begins to have an unhelpful effect on how someone functions, responds, or works.
+
+**Status:** Confirmed.
+
+## Rebalance
+**Draft `/LIA` explanation:** Taking action to recover, reset, or restore effective functioning after pressure has become unhelpful stress.
+
+**Status:** Confirmed.
+
+## Strengths
+Capabilities, qualities, or ways of working that someone can use effectively.
+
+## Weaknesses / areas where support is needed
+Areas where someone is less strong, less experienced, or benefits from help. The statement is not asking whether someone is “weak” as a person.
+
+## Motivations
+The things that tend to give someone energy, commitment, or a reason to act.
+
+## Influence
+The effect someone's behaviour, communication, expertise, decisions, or presence has on other people. It does not require formal authority.
+
+## Overall goal
+The larger outcome the group, team, activity, or organisation is trying to achieve.
+
+## Systems, processes and culture
+- **Systems:** formal or informal structures through which work happens.
+- **Processes:** ways decisions, tasks, approvals, information, or coordination happen.
+- **Culture:** norms and expectations about how people behave and work together.
+
+## External environment
+Relevant changes outside the immediate team that can affect the work. In ATLAS this might include collaboration-level changes, funding or institutional constraints, technology, schedules, policy, or broader scientific developments. It does not have to mean a commercial “marketplace”.
+
+## Physical environment
+The practical setting in which people work: meeting setup, room conditions, remote/hybrid arrangements, accessibility, tools, or other surroundings that affect how people can contribute.
+
+## Values and ethics / “ethical code”
+The principles someone uses to judge what they believe is right, fair, responsible, or acceptable.
+
+## Step forward
+Take more ownership, contribute a view, take an opportunity, or lead something.
+
+## Step up
+Take responsibility or leadership when the situation requires it.
+
+## Serving
+In this framework, supporting others to contribute, develop, succeed, and lead where appropriate. It should not be read as passive or subordinate behaviour.
+
+## Purpose / stay on purpose
+Remain focused on what the work is trying to achieve, especially when there is disagreement, resistance, distraction, or negativity.
+
+## Momentum
+Continued useful progress. It does not mean rushing; it means helping work move rather than stall.
+
+## Vision
+A clear picture of the future state or outcome someone is trying to create. It does not need to be grand or corporate.
+
+## Strategy / strategies
+The chosen approach for moving from the current situation toward the intended goal.
+
+## Measurable outcomes
+Results that can be checked or assessed rather than only described vaguely.
+
+## Operational level
+What a direction or strategy means in day-to-day practice for people, tasks, systems, responsibilities, and ways of working.
+
+## Aligned
+People understand the direction, priorities, and what matters sufficiently to coordinate their actions. Alignment does **not** necessarily mean everyone agrees.
+
+## Determination
+Continuing to orient toward what matters while adapting the approach when needed. It should not be interpreted as stubbornness.
+
+## Excellence
+A high standard of work appropriate to the situation. Avoid treating this as perfection.
+
+## Positive attitude to risk
+A willingness to take sensible, proportionate risks when the potential benefit justifies them. It should not mean being reckless or “liking risk”.
+
+## What's at stake
+The possible consequences of a decision, including benefits, harms, costs, reputational effects, scientific effects, or impacts on people and work.
+
+## Intuition
+Professional judgment or a sense developed through experience. It should not be interpreted as making arbitrary decisions without evidence.
+
+## Robust debate
+Serious, constructive challenge that tests reasoning, evidence, assumptions, and alternatives.
+
+## Assumptions
+Things being treated as true or likely without necessarily having been fully tested.
+
+## Biases
+Patterns in judgment that can shape how information, people, risks, or options are interpreted.
+
+## “Good enough” decision
+A decision that is sufficiently sound for the situation and allows useful progress when further analysis would add little value. It does not mean careless or low-quality work.
+
+## “No action” is the right decision
+A deliberate choice not to act because action would not improve the situation or because waiting is itself the most appropriate option. It is not the same as avoidance.
+
+## Different levels of the organisation
+The different people or parts affected by a decision. In ATLAS this might mean an individual, analysis/team, subgroup, group, combined-performance area, or the wider collaboration rather than a conventional management hierarchy.
+
+## Options and flexibility
+Making decisions in ways that do not unnecessarily lock the group into one path and that preserve the ability to adapt if circumstances change.
+
+## Pace of decision making
+How quickly or deliberately a decision is made. Different situations can justify different speeds.

chatlas_chains-0.3.3/chATLAS_Chains/lia/__init__.py

@@ -0,0 +1,21 @@
+"""Leading in ATLAS feedback-statement clarification support."""
+
+from chATLAS_Chains.lia.guidance import (
+    LIA_STATUS_MESSAGE,
+    LiAResponse,
+    answer_lia_request,
+    is_lia_request,
+    load_statements,
+    select_statements,
+    strip_lia_command,
+)
+
+__all__ = [
+    "LIA_STATUS_MESSAGE",
+    "LiAResponse",
+    "answer_lia_request",
+    "is_lia_request",
+    "load_statements",
+    "select_statements",
+    "strip_lia_command",
+]