satisfactoscript 0.1.0__py3-none-any.whl

satisfactoscript/__init__.py

@@ -0,0 +1,5 @@
+from .core.core import SatisfactoEngine
+from .core.registry import RuleRegistry
+from .core.config import ConfigurationManager
+
+__all__ = ["SatisfactoEngine", "RuleRegistry", "ConfigurationManager"]

satisfactoscript/agentic/agent.py

@@ -0,0 +1,127 @@
+import json
+import os
+from ..semantic import SemanticEngine
+
+class GenBIAgent:
+    """
+    An agentic layer designed to interface natural language queries with the Semantic Engine.
+    It utilizes LLMs to translate human questions into structured semantic queries (JSON).
+    """
+    def __init__(self, semantic_engine: SemanticEngine, default_model="kpi_export_sales"):
+        """
+        Initializes the GenBIAgent with the semantic engine and a default target model.
+        
+        Args:
+            semantic_engine (SemanticEngine): The configured Semantic Engine instance.
+            default_model (str, optional): The default semantic model to use for queries.
+                                           Defaults to "kpi_export_sales".
+        """
+        self.semantic = semantic_engine
+        self.default_model = default_model
+        # On pré-charge le contexte propre (le dictionnaire métier) pour le LLM
+        self.context = self.semantic.get_llm_context(self.default_model)
+
+    def ask(self, question: str):
+        """
+        Takes a natural language question, queries the LLM API to translate it,
+        and executes the corresponding semantic query to return a PySpark DataFrame.
+        
+        Args:
+            question (str): The natural language question from the user.
+            
+        Returns:
+            DataFrame: The resulting PySpark DataFrame containing the answer, 
+                       or None if an error occurred during translation or execution.
+        """
+        print(f"👤 [User] Question : '{question}'")
+
+        # 1. Le Prompt Système : On cadenasse l'IA pour éviter les hallucinations
+        system_prompt = f"""You are an expert in Data Anlytics.
+        Your role here is just to translate questions coming from users in JSON request.
+        You have not access to the database. The unique and only thing you need to use is the following semantic dictionary :
+        {self.context}
+        
+        Rules to strictly apply :
+        - You MUST ANSWER with a JSON object. no speech before or after the json object
+        - the JSON object MUST HAVE the EXACT following structure : 
+        {{
+            "metrics": ["metric_name_1"],
+            "group_by": ["dimension_name_1"]
+        }}
+        - Deduce metrics and dimensions regarding the question meaning
+        - If the question has no mention 
+        - If the question does not mention a grouping dimension, return an empty list for "group_by".
+        """
+
+        # 2. Appel au LLM
+        print(f"🤖 [Agent] Réflexion en cours...")
+        llm_response_text = self._call_llm(system_prompt, question)
+
+        # 3. Nettoyage et Parsing du JSON
+        if not llm_response_text:
+            return None
+
+        try:
+            # Les LLMs aiment bien rajouter ```json au début de leurs réponses, on nettoie ça
+            clean_json = llm_response_text.replace('```json', '').replace('```', '').strip()
+            query_params = json.loads(clean_json)
+            print(f"🧠 [Agent] Traduction réussie : {query_params}")
+        except Exception as e:
+            print(f"❌ [Agent] Erreur de parsing JSON. L'IA a désobéi. Réponse brute : \n{llm_response_text}")
+            return None
+
+        # 4. Exécution sur le cluster Spark via votre SemanticEngine
+        print(f"🚀 [Agent] Exécution de la requête sur Databricks...")
+        try:
+            df_result = self.semantic.query(
+                model_name=self.default_model,
+                metrics=query_params.get("metrics", []),
+                group_by=query_params.get("group_by", [])
+            )
+            return df_result
+        except Exception as e:
+            print(f"❌ [Agent] Erreur lors de l'exécution PySpark : {e}")
+            return None
+
+    def _call_llm(self, system_prompt: str, user_question: str) -> str:
+        """
+        Internal method to make the network call to the LLM API (OpenAI).
+        
+        Args:
+            system_prompt (str): The strictly formatted system context and instructions.
+            user_question (str): The natural language user query.
+            
+        Returns:
+            str: The raw text response from the LLM, expected to be a JSON string.
+        """
+        try:
+            import openai
+        except ImportError:
+            print("❌ [Agent] La librairie 'openai' n'est pas installée. Faites un `pip install openai`.")
+            return None
+
+        # On récupère la clé depuis les variables d'environnement (vide par défaut pour l'instant)
+        api_key = os.environ.get("OPENAI_API_KEY", "")
+
+        if not api_key:
+            print("⚠️ [Agent] OPENAI_API_KEY manquante. Simulation de réponse JSON pour le test...")
+            # Simulation en attendant votre clé !
+            return '{"metrics": ["gross_revenue"], "group_by": ["platform"]}'
+
+        try:
+            client = openai.OpenAI(api_key=api_key)
+
+            response = client.chat.completions.create(
+                model="gpt-4o",  # Modèle standard actuel
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_question}
+                ],
+                # TEMPÉRATURE À 0 : C'est le secret ! On veut une traduction logique, pas de la créativité.
+                temperature=0.0
+            )
+            return response.choices[0].message.content
+
+        except Exception as e:
+            print(f"❌ [Agent] Erreur de communication avec l'API OpenAI : {e}")
+            return None

satisfactoscript/core/__init__.py

@@ -0,0 +1,5 @@
+from .core import SatisfactoEngine
+from .registry import RuleRegistry
+from .config import ConfigurationManager
+
+__all__ = ["SatisfactoEngine", "RuleRegistry", "ConfigurationManager"]

satisfactoscript/core/config.py

@@ -0,0 +1,144 @@
+"""
+Configuration module. Handles YAML loading and Environment detection.
+Includes auto-discovery mechanism to find config.yaml at project root.
+"""
+import yaml
+import os
+
+class ConfigurationManager:
+    """
+    Manages the loading and retrieval of configuration from a YAML file.
+    Automatically detects the current environment by testing catalog access.
+    """
+    def __init__(self, spark, config_path=None):
+        """
+        Initializes the ConfigurationManager.
+        
+        Args:
+            spark (SparkSession): The active SparkSession used to verify catalog access.
+            config_path (str, optional): Absolute path to the config.yaml file.
+                                         If not provided, the framework will attempt
+                                         to auto-discover it by searching parent directories.
+                                         
+        Raises:
+            FileNotFoundError: If the configuration file cannot be found.
+        """
+        self.spark = spark
+        self.config = {}
+        self.current_env_name = None
+        self.db_prefix = None
+        
+        # 1. Path Resolution logic
+        final_path = config_path
+        
+        if not final_path:
+            # Try to auto-discover at current location or parents
+            print("[Config] No path provided. Searching for 'config.yaml' in parent directories...")
+            final_path = self._find_config_upwards("config.yaml")
+            
+        if final_path:
+            self._load_config_file(final_path)
+            self.current_env_name = self._detect_environment()
+            self.db_prefix = self.get_value("catalog")
+        else:
+            # Critical error: Framework cannot run without config
+            raise FileNotFoundError(
+                "[Config] CRITICAL: 'config.yaml' not found in current directory or any parent directory. "
+                "Please verify your project structure."
+            )
+
+    def _find_config_upwards(self, filename):
+        """
+        Searches for a file starting from current working directory and moving up.
+        
+        Args:
+            filename (str): The name of the file to search for.
+            
+        Returns:
+            str: Absolute path to the file if found, else None.
+        """
+        current_dir = os.getcwd()
+        
+        # Loop until we hit the root of the filesystem
+        while True:
+            check_path = os.path.join(current_dir, filename)
+            if os.path.exists(check_path):
+                print(f"   [Config] Auto-discovered config file at: {check_path}")
+                return check_path
+            
+            parent_dir = os.path.dirname(current_dir)
+            if parent_dir == current_dir:
+                # We hit the filesystem root (e.g. /) without finding the file
+                return None
+            current_dir = parent_dir
+
+    def _load_config_file(self, path):
+        """
+        Loads the YAML configuration file into the object's state.
+        
+        Args:
+            path (str): The absolute path to the YAML file.
+            
+        Raises:
+            ValueError: If the YAML file contains syntax errors.
+        """
+        print(f"   [Config] Loading configuration from: {path}")
+        try:
+            with open(path, 'r') as f:
+                self.config = yaml.safe_load(f)
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Error parsing YAML file: {exc}")
+
+    def _detect_environment(self):
+        """
+        Auto-detects the active environment by iterating through the 'priority_check'
+        list in the config and attempting to connect to the associated catalog.
+        
+        Returns:
+            str: The name of the successfully detected environment.
+            
+        Raises:
+            EnvironmentError: If no catalogs defined in the configuration are accessible.
+        """
+        envs = self.config.get("environments", {})
+        priority = self.config.get("priority_check", envs.keys())
+
+        print("   [Config] Auto-detecting environment...")
+
+        for env_name in priority:
+            if env_name not in envs:
+                continue
+            
+            catalog = envs[env_name].get("catalog")
+            try:
+                # Use a read-only command which is more stable than USE CATALOG.
+                # It checks for accessibility without changing the session's state.
+                self.spark.sql(f"SHOW SCHEMAS IN `{catalog}`").limit(1).collect()
+                print(f"   [Config] Success: Connected to catalog '{catalog}'. Environment is '{env_name.upper()}'.")
+                return env_name
+            except Exception:
+                continue
+        
+        raise EnvironmentError("Could not connect to any catalog defined in the configuration file.")
+
+    def get_value(self, key):
+        """
+        Retrieves a configuration value specific to the currently active environment.
+        
+        Args:
+            key (str): The configuration key to retrieve.
+            
+        Returns:
+            Any: The value associated with the key, or None if not found or no env is active.
+        """
+        if not self.current_env_name: return None
+        return self.config["environments"][self.current_env_name].get(key)
+    
+    def get_db(self):
+        """
+        Retrieves the database (catalog) prefix for the current environment.
+        
+        Returns:
+            str: The database/catalog prefix.
+        """
+        return self.db_prefix