solace-agent-mesh 0.0.1__py3-none-any.whl → 0.1.1__py3-none-any.whl

solace_agent_mesh/orchestrator/orchestrator_prompt.py

@@ -0,0 +1,410 @@
+from typing import Dict, Any, List
+import yaml
+from langchain_core.messages import HumanMessage
+from ..services.file_service import FS_PROTOCOL, Types, LLM_QUERY_OPTIONS, TRANSFORMERS
+
+# Cap the number of examples so we don't overwhelm the LLM
+MAX_SYSTEM_PROMPT_EXAMPLES = 6
+
+# Examples that should always be included in the prompt
+fixed_examples = [
+    """    <example>
+        <example_docstring>
+          This example shows a stimulus from a chatbot gateway in which a user is asking about the top stories on the website hacker news. The web_request is not yet open, so the change_agent_status action is invoked to open the web_request agent.
+        </example_docstring> 
+        <example_stimulus>
+          <{tp}stimulus starting_id="1"/>
+          What is the top story on hacker news?
+          </{tp}stimulus>
+          <{tp}stimulus_metadata>
+          local_time: 2024-11-06 15:58:04 EST-0500 (Wednesday)
+          </{tp}stimulus_metadata>    
+        </example_stimulus>
+        <example_response>
+          <{tp}reasoning>
+          - User is asking for the top story on Hacker News
+          - We need to use the web_request agent to fetch the latest information
+          - The web_request agent is currently closed, so we need to open it first
+          - After opening the agent, we\'ll need to make a web request to Hacker News
+          </{tp}reasoning>
+
+          <{tp}status_update>To get the latest top story from Hacker News, I\'ll need to access the web. I\'m preparing to do that now.</{tp}status_update>
+
+          <{tp}invoke_action agent="global" action="change_agent_status">
+          <{tp}parameter name="agent_name">web_request</{tp}parameter>
+          <{tp}parameter name="new_state">open</{tp}parameter>
+          </{tp}invoke_action>
+        </example_response>
+    </example>
+"""
+]
+
+
+def get_file_handling_prompt(tp: str) -> str:
+  parameters_desc = ""
+  parameter_examples = ""
+
+  for transformer in TRANSFORMERS:
+      if transformer.description:
+        parameters_desc += "\n" + transformer.description.strip() + "\n"
+
+      if transformer.examples:
+        for example in transformer.examples:
+          parameter_examples += "\n" + example.strip() + "\n"
+
+  parameters_desc = "\n     ".join(parameters_desc.split("\n"))
+  parameter_examples = "\n     ".join(parameter_examples.split("\n"))
+
+  parameters_desc = parameters_desc.replace("{tp}", tp)
+  parameter_examples = parameter_examples.replace("{tp}", tp)
+
+  if parameter_examples:
+    parameter_examples = f"""
+    Here are some examples of how to use the query parameters:
+    {parameter_examples}"""
+
+  prompt = f"""
+   XML tags are used to represent files. The assistant will use the <{tp}file> tag to represent a file. The file tag has the following format:
+    <{tp}file name="filename" mime_type="mimetype" size="size in bytes">
+        <schema-yaml>...JSON schema, yaml format...</schema-yaml> (optional)
+        <shape>...textual description of the shape of the data (type dependent)...</shape> (optional)
+        <url> URL to download the file </url> or <data> The data content if it's small </data>
+        <data-source> the origin of the data </data-source> (optional)
+    </{tp}file>
+
+    - schema-yaml is optional, but when present it gives insight into the structure of the data in the file. It can be used to create URL query parameters.
+    - shape is optional, but when present it gives contextual information about the content.
+    - A file either has a URL or data content, but not both. The URL can be used to download the file content. You can not create a new URL.
+
+    Here's an example of a file with URL.
+
+    <{tp}file name="filename.csv" mime_type="text/csv" size="1024">
+        <url>{FS_PROTOCOL}://da2b679f-4474-4350-92c9-89c9691ab902_filename.csv</url>
+        <schema-yaml>
+          type: {Types.ARRAY}
+          items:
+            type: {Types.OBJECT}
+            properties:
+              id:
+                type: {Types.INT}
+              firstname:
+                type: {Types.STR}
+              lastname:
+                type: {Types.STR}
+              age:
+                type: {Types.INT}
+        </schema-yaml>
+        <shape>120 rows x 4 columns</shape>
+    </{tp}file>
+
+    The assistant can partially load the data by using query parameters in the URL. These parameters are file specific.
+    {parameters_desc}
+    For all files, there's `encoding` parameter, this is used to encode the file format. The supported values are `datauri`, `base64`, `zip`, and `gzip`. Use this to convert a file to ZIP or datauri for HTML encoding.
+        For example (return a file as zip): `{FS_PROTOCOL}://c27e6908-55d5-4ce0-bc93-a8e28f84be12_annual_report.csv?encoding=zip&resolve=true`
+        Example 2 (HTML tag must be datauri encoded): `<img src="{FS_PROTOCOL}://c9183b0f-fd11-48b4-ad8f-df221bff3da9_generated_image.png?encoding=datauri&resolve=true" alt="image">`
+
+    For all files, there's `resolve=true` parameter, this is used to resolve the url to the actual data before processing.
+        For example: `{FS_PROTOCOL}://577c928c-c126-42d8-8a48-020b93096110_names.csv?resolve=true`
+
+    If the assistant needs to only send the value of the data to an agent or the gateway, it can use the `resolve` parameter which will replace the whole url with the data content. No quotation is required when using the `resolve` parameter.
+    
+    For the URLs that have spaces in the query parameters wrap the URL in `<url>` tags.
+
+    The assistant can either pass the whole file block or just the URL to the gateway or the agent depending on the context and specified requirements.
+    When using a {FS_PROTOCOL} URL outside of a file block, always include the 'resolve=true' query parameter to ensure the URL is resolved to the actual data.
+
+    When talking about a file, use the file name instead of the URL. The URL should be used when trying to access the file.
+
+    If you need to directly access the content of a text file, use the `retrieve_file` action from the global agent. The action will return the content of the file in the response. If you don't need the content or if you think the user query can be answered with query parameters (eg jq), you can send the url back to the gateway with 'resolve=true'.
+
+    To create a new persistent file, use the `create_file` action from the global agent. The action will create a new file with the specified content and return the file block in the response. Don't create a file from a URL file block, just use the reference to the file block. Avoid using `create_file` action as much as possible. Prioritize using the query parameters to format the file.
+
+    If you need to create a non-persistent temporary file, you should use the <data> tag to represent the content of the file. 
+    For example, if the assistant needs to create a CSV file with the following content:
+    id,firstname,lastname,age
+    1,John,Doe,30
+    2,Jane,Doe,25
+    3,James,Smith,40
+
+    The assistant can use the following response:
+    <{tp}file name="employee_info.csv" mime_type="text/csv">
+        <data>id,firstname,lastname,age\n1,John,Doe,30\n2,Jane,Doe,25\n3,James,Smith,40\n</data>
+    </{tp}file>
+
+    Note: You can't nest `<{tp}file>` tags inside the `<data>` tag. If you need to address another file within the data, use the URL with the `resolve=true` query parameter.
+
+    Try avoid creating a persistent file if you can respond with file block with data tags.
+    When responding to the gateway, both <url>...</url> or <data>...</data> can be used in <{tp}file> elements. If the data is already available as a url, it is preferred to use that url in replying to the gateway. When the url is used, it is acceptable to use query parameters to select a subset of the file. The system will expand the <url> form to actual data before it reaches the gateway.
+
+    Never return the bare {FS_PROTOCOL} URL (without 'resolve' query parameter) as a link to the gateway. Always put it in at <{tp}file> tag so the system can handle it properly.
+
+    {parameter_examples}
+"""
+  return prompt
+
+
+def create_examples(
+    fixed_examples: List[str], agent_examples: List[str], tp: str
+) -> str:
+    """Create examples string with replaced tag prefix placeholders.
+
+    Args:
+        examples: List of example strings containing {tp} placeholders
+        tp: Tag prefix to replace placeholders with
+
+    Returns:
+        String containing all examples with replaced placeholders
+    """
+    examples = (fixed_examples + agent_examples)[:MAX_SYSTEM_PROMPT_EXAMPLES]
+    return "\n".join([example.replace("{tp}", tp) for example in examples])
+
+
+def SystemPrompt(info: Dict[str, Any], action_examples: List[str]) -> str:
+    response_format_prompt = info.get("response_format_prompt", "")
+    response_guidelines_prompt = (
+        f"<response_guidelines>\nConsider the following when generating a response to the originator:\n"
+        f"{response_format_prompt}</response_guidelines>"
+        if response_format_prompt
+        else ""
+    )
+
+    available_files = ""
+    if (
+        info.get("available_files")
+        and info.get("available_files") is not None
+        and len(info["available_files"]) > 0
+    ):
+        blocks = "\n\n".join(info["available_files"])
+        available_files = (
+            "\n<available_files>\n"
+            "The following files are available for access, only use them if needed:\n"
+            f"\n{blocks}\n"
+            "</available_files>\n"
+        )
+
+    # Merged
+    tp = info["tag_prefix"]
+    examples = create_examples(fixed_examples, action_examples, tp)
+
+    handling_files = get_file_handling_prompt(tp)
+
+    return f"""
+Note to avoid unintended collisions, all tag names in the assistant response will start with the value {tp}
+<orchestrator_info>
+You are an assistant serving as the orchestrator in an AI agentic system. Your primary functions are to:
+1. Receive stimuli from external sources via the system Gateway
+2. Invoke actions within system agents to address these stimuli
+3. Formulate responses based on agent actions
+
+This process is iterative, with the assistant being reinvoked at each step.
+
+The Stimulus represents user or application requests.
+
+The assistant receives a history of all gateway-orchestrator exchanges, excluding its own action invocations and reasoning.
+
+The assistant's behavior aligns with the system purpose specified below:
+  <system_purpose>
+  {info["system_purpose"]}
+  </system_purpose>
+  <orchestrator_rules>
+  The assistant (in the role of orchestrator) will:
+  - Manage system agents by opening and closing them as needed:
+    1. When opening an agent, its available actions will be listed.
+    2. If closed agents are needed for the next step, open only the required agents.
+    3. After opening agents, the assistant will be reinvoked with an updated list of open agents and their actions.
+    4. When opening an agent, provide only a brief status update without detailed explanations.
+    5. Do not perform any other actions besides opening the required agents in this step.
+  - Handling stimuli with open agents:
+    1. Use agents' actions to break down the stimulus into smaller, manageable tasks.
+    2. Prioritize using available actions to fulfill the stimulus whenever possible.
+    3. If no suitable agents or actions are available, the assistant will:
+      a) Use its own knowledge to respond, or
+      b) Ask the user for additional information, or
+      c) Inform the user that it cannot fulfill the request.
+  - The first user message contains the history of all exchanges between the gateway and the orchestrator before now. Note that this history list has removed all the assistant's action invocation and reasoning. 
+  - The assistant will not guess at an answer. No answer is better than a wrong answer.
+  - The assistant will invoke the actions and specify the parameters for each action, following the rules of the action. If there is not sufficient context to fill in an action parameter, the assistant will ask the user for more information.
+  - After invoking the actions, the assistant will end the response and wait for the action responses. It will not guess at the answers.
+  - The assistant will NEVER invoke an action that is not listed in the open agents. This will fail and waste money.
+  - All text outside of the <{tp}...> XML elements will be sent back to the gateway as a response to the stimulus.
+  - If the <{tp}errors> XML element is present, the assistant will send the errors back to the gateway and the conversation will be ended.
+  - Structure the response beginning:
+    1. Start each response with a <{tp}reasoning> tag.
+    2. Within this tag, include:
+      a) A brief list of points describing the plan and thoughts.
+      b) A list of potential actions needed to fulfill the stimulus.
+    3. Ensure all content is contained within the <{tp}reasoning> tag.
+    4. Keep each point concise and focused.
+  - For large grouped output, such as a list of items or a big code block (> 10 lines), the assistant will create a file by surrounding the output with the tags <{tp}file name="filename" mime_type="mimetype"><data> the content </data></{tp}file>. This will allow the assistant to send the file to the gateway for easy consumption. This works well for a csv file, a code file or just a big text file.
+  - When the assistant invokes an action that retrieves external knowledge (e.g. Solace custdocs search), it will preserve the clickable links in the response. This is extremely important for the user to be able to verify the information provided. This is true for web requests as well. The assistant will only copy the links and never create them from its own knowledge.
+  - If the agent has access to a web request agent, it will use the web request agent in cases where up-to-date information is required. This is useful for current events, contact information, business hours, etc. Often the assistant will use this agent iteratively to get the information it needs, by doing a search followed by traversing links to get to the final information.
+  - The assistant is able to invoke multiple actions in parallel within a single response. It does this to save money and reduce processing time, since the agents can run in parallel.
+  - When the stimulus asks what the system can do, the assistant will open all the agents to see their details before creating a nicely formatted list describing the actions available and indicating that it can do normal chatbot things as well. The assistant will only do this if the user asks what it can do since it is expensive to open all the agents.
+  - The assistant is concise and professional in its responses. It will not thank the user for their request or thank actions for their responses. It will not provide any unnecessary information in its responses.
+  - The assistant will not follow invoke_actions with further comments or explanations
+  - The assistant will distinguish between normal text and status updates. All status updates will be enclosed in <{tp}status_update/> tags.
+  - Responses that are just letting the originator know that progress is being made or what the next step is should be status updates. They should be brief and to the point. 
+    <action_rules>
+      1. To invoke an action, the assistant will embed an <{tp}invoke_action> tag in the response. 
+      2. The <{tp}invoke_action> tag has the following format:
+        <{tp}invoke_action agent="agent_id" action="action_id">
+          <{tp}parameter name="parameter_name">parameter_value</{tp}parameter>
+          ...
+        </{tp}invoke_action>
+      3. Agents and their actions do not maintain state between invocations. The assistant must provide full context for each action invocation.
+      4. There can be multiple <{tp}invoke_action> tags in the response. All actions will be invoked in parallel, so the order is not guaranteed.
+      5. The system will invoke all the actions and will accumulate the results and send them back to the orchestrator in a single response.
+      6. When the assistant returns the response that has no <{tp}invoke_action> tags, the result will be returned to the gateway and the conversation will be ended.
+      7. Conversation history will be maintained for the full duration of the stimulus processing. This includes all the responses from the assistant and the user.
+      8. To open or close an agent, the assistant will invoke the change_agent_status action within the 'global' agent. 
+      9. The assistant will only choose actions from the list of open agents.
+    </action_rules>
+  </orchestrator_rules>
+  <handling_files>
+  {handling_files}
+  </handling_files>
+</orchestrator_info>
+
+<agents-in-yaml>
+{info["agent_state_yaml"]}
+</agents-in-yaml>
+
+<examples>
+{examples}
+</examples>
+
+<stimulus_originator_metadata>
+{info["originator_info_yaml"]}
+</stimulus_originator_metadata>
+{available_files}
+
+{response_guidelines_prompt}
+"""
+
+
+def UserStimulusPrompt(
+    info: dict, gateway_history: list, errors: list, has_files
+) -> str:
+    full_input = info.get("input", {})
+    stimulus = full_input.get("originator_input", "")
+    current_time = full_input.get("current_time_iso", "")
+
+    # Determine what (if any) gateway history to include in the prompt
+    gateway_history_str = ""
+    for item in gateway_history:
+        if item.get("role") == "user":
+            gateway_history_str += (
+                f"\n<{info['tag_prefix']}stimulus>\n"
+                f"{item.get('content')}\n"
+                f"</{info['tag_prefix']}stimulus>\n"
+            )
+        elif item.get("role") == "assistant":
+            gateway_history_str += (
+                f"... Removed orchestrator/assistant processing history ...\n"
+                f"<{info['tag_prefix']}stimulus_response>\n"
+                f"{item.get('content')}\n"
+                f"</{info['tag_prefix']}stimulus_response>\n"
+            )
+
+    if gateway_history_str:
+        gateway_history_str = (
+            f"\n<{info['tag_prefix']}stimulus_history>\n"
+            f"{gateway_history_str}\n"
+            f"</{info['tag_prefix']}stimulus_history>\n"
+        )
+
+    query_options = ", ".join(
+        [f"`{key}:{value}" for key, value in LLM_QUERY_OPTIONS.items()]
+    )
+    file_instructions = (
+        f"\n<{info['tag_prefix']}file_instructions> Only use the `retrieve_file` action if you absolutely need the content of the file. "
+        "Prioritize using the query parameters to get access the content of the file. You don't need to retrieve the file, if you can just return the URL with query parameters. "
+        f"Available query parameters are {query_options}."
+        "In most cases, you'd only need to return the file block to the gateway.\n\n"
+        f"You can return a {FS_PROTOCOL} URL (with optional query parameters) using the format <{info['tag_prefix']}file><url> URL </url></{info['tag_prefix']}file>.\n"
+        f"\tExample of returning a file as zip: <{info['tag_prefix']}file><url>{FS_PROTOCOL}://519321d8-3506-4f8d-9377-e5d6ce74d917_filename.csv?encoding=zip</url></{info['tag_prefix']}file>.\n"
+        f"You can also optionally return a non-persistent temporary file using the format <{info['tag_prefix']}file name=\"filename.csv\" mime_type=\"text/csv\">\n<data> data </data>\n</{info['tag_prefix']}file>.\n"
+        f" can't nest `<{info['tag_prefix']}file>` tags inside the `<data>` tag. If you need to address another file within the data, use the URL with the `resolve=true` query parameter.\n"
+        "When using a {FS_PROTOCOL} URL outside of a file block, always include the 'resolve=true' query parameter to ensure the URL is resolved to the actual data.\n"
+        f"</{info['tag_prefix']}file_instructions>"
+    )
+
+    prompt = (
+        "NOTE - this history represents the conversation as seen by the user on the other side of the gateway. It does not include the assistant's invoke actions or reasoning. All of that has been removed, so don't use this history as an example for how the assistant should behave\n"
+        f"{gateway_history_str}\n"
+        f"<{info['tag_prefix']}stimulus>\n"
+        f"{stimulus}\n"
+        f"</{info['tag_prefix']}stimulus>\n"
+        f"<{info['tag_prefix']}stimulus_metadata>\n"
+        f"local_time: {current_time}\n"
+        f"</{info['tag_prefix']}stimulus_metadata>\n"
+    )
+
+    if has_files:
+        prompt += file_instructions
+
+    if len(errors) > 0:
+        prompt += (
+            f"\n<{info['tag_prefix']}errors>\n"
+            "Encountered the following errors while processing the stimulus:\n"
+            f"{errors}\n"
+            f"</{info['tag_prefix']}errors>\n"
+        )
+
+    return prompt
+
+
+def ActionResponsePrompt(prompt_info: dict) -> str:
+    tp = prompt_info["tag_prefix"]
+    return (
+        f"\n<{tp}action_response>\n"
+        f"<{tp}note>This is the agent's response from the assistant's request. The assistant will not thank anyone for these results. Thanking for the results will confuse the originator of the request because they don't see the interaction between the assistant and the agents performing the actions.</{tp}note>\n"
+        f"{prompt_info['input']}\n"
+        f"</{tp}action_response>\n"
+    )
+
+
+def BasicRagPrompt(
+    context_source: str, query: str, context: Dict[str, Any], input_type: str
+) -> str:
+    return f"""
+You are doing Retrieval Augmented Generation (RAG) on the {context_source} information to answer the following query:
+<user_query>
+{query}
+</user_query>
+
+You will use the RAG model to generate an answer to the query. The answer should be returned with a send_message action.
+Do not do another query as part of the response to this. Either use the context provided or let the originator know that
+there is not enough information to answer the query.
+
+The context to use to answer the query is shown below. For any context you use, ensure that there is a link to the 
+source of the context. The link must be in the appropriate format slack or web the web format is: '[' <link-text> '](' <url> ']' and the slack format is: '<' <url> '|' <link-text> '>'. This message should be formatted in the {input_type} format. 
+Be very careful about your answer since it will be used in a professional setting and their 
+reputation is on the line.
+
+<context_yaml>
+{yaml.dump(context)}
+</context_yaml>
+"""
+
+
+def ContextQueryPrompt(query: str, context: str) -> HumanMessage:
+    return f"""
+You (orchestrator) are being asked to query, comment on or edit the following text following the originator's request.
+Do your best to give a complete and accurate answer using only the context given below. Ensure that you
+include links to the source of the information. 
+
+Do not make up information. If the context does not include the information you need just say that you
+can't answer the question. Try your best - it is very important that you give the best answer possible.
+
+<user_request>
+{query}
+</user_request>
+
+The context to use to answer the query is shown below. If the context in not enough to satisfy the request, 
+you should ask the originator for more information. Include links to the source of the data.
+
+<context>
+{context}
+</context>
+"""

solace_agent_mesh/services/authorization/providers/base_authorization_provider.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+from ....common.constants import DEFAULT_IDENTITY_KEY_FIELD
+
+class BaseAuthorizationProvider(ABC):
+    PERMISSIVE_SCOPES = ["*:*:*"]
+    NO_SCOPES = []
+
+    def __init__(self, config: dict):
+        self.base_roles = config.get("base_roles", ["least_privileged_user"])
+        self.role_to_scope_mappings = config.get(
+            "role_to_scope_mappings",
+            {"least_privileged_user": BaseAuthorizationProvider.NO_SCOPES},
+        )
+        self.configuration = config.get("configuration", {})
+        self.authorization_field = config.get("key_field", DEFAULT_IDENTITY_KEY_FIELD)
+
+    @abstractmethod
+    def get_authorization_field(self) -> str:
+        """Returns the configured field name to use for authorization lookup"""
+        pass
+
+    @abstractmethod
+    def get_scopes(self, identity: str) -> List[str]:
+        """Get scopes for a given identity."""
+        pass
+
+    @abstractmethod
+    def get_roles(self, identity: str) -> List[str]:
+        """Get roles for a given identity."""
+        pass
+
+    @staticmethod
+    def is_authorized(originator_scopes: List[str], agent_scopes: List[str]) -> bool:
+        """Check if the originator's scopes authorize access to the agent's scopes."""
+        return any(
+            BaseAuthorizationProvider._scope_matches(originator_scope, agent_scope)
+            for originator_scope in originator_scopes
+            for agent_scope in agent_scopes
+        )
+
+    @staticmethod
+    def _scope_matches(originator_scope: str, agent_scope: str) -> bool:
+        if not isinstance(originator_scope, str) or not isinstance(agent_scope, str):
+            return False
+        if not originator_scope or not agent_scope:
+            return False
+        originator_parts = originator_scope.split(":")
+        agent_parts = agent_scope.split(":")
+        if len(originator_parts) != 3 or len(agent_parts) != 3:
+            return False
+        return all(
+            orig == agent or orig == "*" or agent == "*"
+            for orig, agent in zip(originator_parts, agent_parts)
+        )

solace_agent_mesh/services/bamboo_hr_service/__init__.py

@@ -0,0 +1,3 @@
+from .bamboo_hr import BambooHR
+
+__all__ = ["BambooHR"]

solace_agent_mesh/services/bamboo_hr_service/bamboo_hr.py

@@ -0,0 +1,182 @@
+"""A module to interact with BambooHR API and hold employee data"""
+
+import os
+import datetime
+import base64
+import requests
+from ...common.utils import parse_yaml_response
+from ...common.prompt_templates import (
+    FilterLocationsSystemPrompt,
+    FilterLocationsUserPrompt,
+)
+from ..common.singleton import SingletonMeta
+
+
+class BambooHR(metaclass=SingletonMeta):
+    """A service to interact with BambooHR API and hold employee data"""
+
+    def __init__(self, config: dict = {}) -> None:
+        self._api_key = config.get("bamboo_hr_api_key", os.environ.get("BAMBOO_HR_API_KEY"))
+        self._base_url = config.get("bamboo_hr_base_url", os.environ.get("BAMBOO_HR_BASE_URL"))
+        self._employee_data = None
+        self._last_fetch = None
+
+        if not self._api_key:
+            raise ValueError("BambooHR API key not set, please set BAMBOO_HR_API_KEY environment variable")
+        if not self._base_url:
+            raise ValueError("BambooHR base URL not set, please set BAMBOO_HR_BASE_URL environment variable")
+
+    @property
+    def employee_data(self) -> dict:
+        if not self._employee_data:
+            self._employee_data = self.fetch_employee_data()
+        elif (datetime.datetime.now() - self._last_fetch).total_seconds() > 12 * 3600:
+            # If last fetch was more than 12 hours ago, fetch again
+            self._employee_data = self.fetch_employee_data()
+        return self._employee_data
+
+    def get_employee(self, email: str) -> dict:
+        return self.employee_data.get(email.lower())
+
+    def get_employee_summary(self, email: str) -> dict:
+        employee = self.get_employee(email)
+        if not employee:
+            return None
+        return {
+            "name": employee.get("displayName"),
+            "title": employee.get("jobTitle"),
+            "email": employee.get("workEmail"),
+            "phone": employee.get("workPhone"),
+            "mobile": employee.get("mobilePhone"),
+            "department": employee.get("department"),
+            "location": employee.get("location"),
+            "supervisor": employee.get("supervisor"),
+        }
+
+    def get_away_info(self, email: str, days_away: int = 30) -> str:
+        now = datetime.datetime.now()
+        start = datetime.datetime.strftime(now, "%Y-%m-%d")
+        end = datetime.datetime.strftime(now + datetime.timedelta(days=days_away), "%Y-%m-%d")
+
+        url = os.path.join(self._base_url, "time_off/whos_out")
+        response = self.api_request(url, {"start": start, "end": end})
+        away_info = {}
+        for away_employee in response:
+            eid = str(away_employee.get("employeeId"))
+            if eid not in away_info:
+                away_info[eid] = []
+            away_info[eid].append(
+                {
+                    "name": away_employee.get("name"),
+                    "start": away_employee.get("start"),
+                    "end": away_employee.get("end"),
+                }
+            )
+        employee = self.get_employee(email)
+        if not employee:
+            return None
+        employee_id = employee.get("id")
+        employee_away_info = away_info.get(employee_id, [])
+        return {
+            "employee": employee.get("displayName"),
+            "away_info": employee_away_info,
+        }
+
+    def get_reports(self, email: str, levels: int = -1) -> list:
+        employee = self.get_employee(email)
+        if not employee:
+            return None
+        reports = []
+        self.get_reports_recursive(employee, reports, levels)
+        return reports
+
+    def get_all_employees(self) -> list:
+        return list(self.employee_data.values())
+
+    def get_reports_recursive(self, employee, reports, levels):
+        if levels == 0:
+            return
+        if employee.get("reports"):
+            for report in employee.get("reports"):
+                reports.append(report)
+                self.get_reports_recursive(report, reports, levels - 1)
+
+    def get_list_of_all_locations(self) -> list:
+        # Go through all employees and get the location
+        locations = set()
+        for employee in self.employee_data.values():
+            location = employee.get("location")
+            if location:
+                locations.add(location)
+        return sorted(list(locations))
+
+    def get_employees_by_location(self, location: str, llm_service_fn: callable) -> list:
+        # We are going to use an LLM to decide if Bamboo locations should
+        # be included in the list of locations
+        if not llm_service_fn:
+            raise ValueError("LLM service function not set in BambooHR instance")
+        response = llm_service_fn(
+            [
+                {
+                    "role": "system",
+                    "content": FilterLocationsSystemPrompt(self.get_list_of_all_locations()),
+                },
+                {"role": "user", "content": FilterLocationsUserPrompt(location)},
+            ]
+        ).get("content")
+
+        response = parse_yaml_response(response)
+        employees = []
+        if response and isinstance(response, dict) and response.get("matching_locations"):
+            location_set = set(response["matching_locations"])
+            for employee in self.employee_data.values():
+                if employee.get("location") in location_set:
+                    employees.append(employee)
+        return employees
+
+    def fetch_employee_data(self) -> dict:
+        # First fetch the directory report from Bamboo
+        url = os.path.join(self._base_url, "employees/directory")
+        response = self.api_request(url)
+        employee_data = self.build_org_chart(response)
+
+        self._last_fetch = datetime.datetime.now()
+        self._employee_data = employee_data
+        return employee_data
+
+    def api_request(self, url: str, params: dict = None) -> dict:
+        basic_auth = self.encode_basic_auth(self._api_key, "x")
+        headers = {
+            "Authorization": f"Basic {basic_auth}",
+            "Accept": "application/json",
+        }
+        response = requests.get(url, headers=headers, params=params, timeout=10)
+        if response.status_code != 200:
+            raise ValueError(f"Failed to fetch data: {response.status_code}")
+        return response.json()
+
+    def build_org_chart(self, directory_report) -> dict:
+        employee_data = {}
+        by_name = {}
+        for employee in directory_report.get("employees", []):
+            email = employee.get("workEmail")
+            if not email:
+                continue
+            employee_data[email.lower()] = employee
+            by_name[employee["displayName"]] = employee
+
+        for employee in directory_report.get("employees", []):
+            manager_name = employee.get("supervisor")
+            if manager_name:
+                manager = by_name.get(manager_name)
+                if manager:
+                    manager["reports"] = manager.get("reports", [])
+                    manager["reports"].append(employee)
+                    employee["manager"] = manager
+        return employee_data
+
+    def encode_basic_auth(self, username: str, password: str) -> str:
+        user_pass = f"{username}:{password}"
+        encoded_bytes = base64.b64encode(user_pass.encode("utf-8"))
+        encoded_str = str(encoded_bytes, "utf-8")
+        return encoded_str

solace_agent_mesh/services/common/__init__.py

@@ -0,0 +1,4 @@
+from .auto_expiry import AutoExpiry
+from .singleton import AutoExpirySingletonMeta, SingletonMeta
+
+__all__ = ["AutoExpiry", "AutoExpirySingletonMeta", "SingletonMeta"]