naas-abi-core 1.4.1__py3-none-any.whl

naas_abi_core/module/Module.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import glob
+import os
+from typing import Dict, List, cast
+
+from naas_abi_core import logger
+from naas_abi_core.engine.engine_configuration.EngineConfiguration import GlobalConfig
+from naas_abi_core.engine.EngineProxy import EngineProxy
+from naas_abi_core.integration.integration import Integration
+from naas_abi_core.module.ModuleAgentLoader import ModuleAgentLoader
+from naas_abi_core.pipeline.pipeline import Pipeline
+from naas_abi_core.services.agent.Agent import Agent
+from naas_abi_core.workflow.workflow import Workflow
+from pydantic import BaseModel, ConfigDict
+from typing_extensions import Generic, Self, TypeVar
+
+
+class ModuleDependencies:
+    __modules: List[str]
+    __services: List[type]
+
+    def __init__(self, modules: List[str], services: List[type]):
+        self.__modules = modules
+        self.__services = services
+
+    def _get_modules(self) -> List[str]:
+        return self.__modules
+
+    def _set_modules(self, modules: List[str]) -> None:
+        self.__modules = modules
+
+    modules = property(_get_modules, _set_modules)
+
+    def _get_services(self) -> List[type]:
+        return self.__services
+
+    def _set_services(self, services: List[type]) -> None:
+        self.__services = services
+
+    services = property(_get_services, _set_services)
+
+
+class ModuleConfiguration(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    global_config: GlobalConfig
+
+
+TConfig = TypeVar("TConfig", bound=ModuleConfiguration)
+
+
+class BaseModule(Generic[TConfig]):
+    """Base interface class for ABI modules."""
+
+    _instances: Dict[type, Self] = {}
+
+    _engine: EngineProxy
+    _configuration: TConfig
+    dependencies: ModuleDependencies = ModuleDependencies(modules=[], services=[])
+
+    __ontologies: List[str] = []
+    __agents: List[type[Agent]] = []
+    __integrations: List[Integration] = []
+    __workflows: List[Workflow] = []
+    __pipelines: List[Pipeline] = []
+
+    def __init__(self, engine: EngineProxy, configuration: TConfig):
+        assert isinstance(configuration, ModuleConfiguration), (
+            "configuration must be an instance of ModuleConfiguration"
+        )
+        logger.debug(f"Initializing module {self.__module__.split('.')[0]}")
+        self._engine = engine
+        self._configuration = configuration
+
+        assert hasattr(self.__class__, "Configuration"), (
+            "BaseModule must have a Configuration class"
+        )
+        assert type(self.__class__.Configuration) is type(ModuleConfiguration), (
+            "BaseModule.Configuration must be a subclass of ModuleConfiguration"
+        )
+
+        self_instance: Self = cast(Self, self)
+
+        self._instances[self.__class__] = self_instance
+
+    @classmethod
+    def get_dependencies(cls) -> List[str]:
+        """Return the list of module dependencies."""
+        return getattr(cls, "dependencies", [])
+
+    @classmethod
+    def get_instance(cls) -> Self:
+        if cls not in cls._instances:
+            raise ValueError(f"Module {cls} not initialized")
+        return cls._instances[cls]
+
+    @property
+    def engine(self) -> EngineProxy:
+        return self._engine
+
+    @property
+    def configuration(self) -> TConfig:
+        return self._configuration
+
+    @property
+    def ontologies(self) -> List[str]:
+        return self.__ontologies
+
+    @property
+    def agents(self) -> List[type[Agent]]:
+        return self.__agents
+
+    @property
+    def integrations(self) -> List[Integration]:
+        return self.__integrations
+
+    @property
+    def workflows(self) -> List[Workflow]:
+        return self.__workflows
+
+    @property
+    def pipelines(self) -> List[Pipeline]:
+        return self.__pipelines
+
+    def on_load(self):
+        logger.debug(f"on_load for module {self.__module__.split('.')[0]}")
+        self.__load_ontologies()
+
+        self.__agents = ModuleAgentLoader.load_agents(self.__class__)
+
+    def on_initialized(self):
+        """
+        Called after all modules have been loaded and the engine is fully initialized.
+
+        Use this method to perform post-initialization steps that require other modules,
+        services, or ontologies to be available and loaded.
+        """
+        logger.debug(f"on_initialized for module {self.__module__.split('.')[0]}")
+
+    def on_unloaded(self):
+        pass
+
+    def __load_ontologies(self):
+        if os.path.exists(os.path.join(self.__module__.split(".")[0], "ontologies")):
+            for file in glob.glob(
+                os.path.join(self.module_path, "ontologies", "**", "*.ttl"),
+                recursive=True,
+            ):
+                self.ontologies.append(file)
+
+
+# class IModule(ABC):
+#     """Base interface class for ABI modules.
+
+#     This class serves as the base interface for all modules in the src/modules directory.
+
+#     The IModule class provides a default loading mechanism.
+
+
+#     The default loading mechanism will:
+#     1. Load all agents from the module's 'agents' directory
+#     2. Initialize module configuration and state
+
+#     Attributes:
+#         agents (List[Agent]): List of agents loaded from the module
+#     """
+
+#     agents: List[Agent]
+#     triggers: List[tuple[tuple[Any, Any, Any], OntologyEvent, Callable]]
+#     ontologies: List[str]
+
+#     def __init__(self, module_path: str, module_import_path: str, imported_module: Any):
+#         self.module_path = module_path
+#         self.module_import_path = module_import_path
+#         self.imported_module = imported_module
+#         self.triggers = []
+#         self.ontologies = []
+#         self.agents = []
+
+#     def check_requirements(self):
+#         if hasattr(self.imported_module, "requirements"):
+#             if not self.imported_module.requirements():
+#                 logger.error(f"❌ Module {self.module_import_path} failed to meet requirements.")
+#                 raise SystemExit(f"Application crashed due to module loading failure: {self.module_import_path}")
+
+#     def load(self):
+#         try:
+#             self.check_requirements()
+#             # self.__load_agents()
+#             self.__load_triggers()
+#             self.__load_ontologies()
+#         except Exception as e:
+#             logger.error(f"❌ Critical error loading module {self.module_import_path}: {e}")
+#             raise SystemExit(f"Application crashed due to module loading failure: {self.module_import_path}")
+
+#     def load_agents(self):
+#         try:
+#             self.__load_agents()
+#         except Exception as e:
+#             import traceback
+#             logger.error(f"❌ Critical error loading agents for module {self.module_import_path}: {e}")
+#             traceback.print_exc()
+#             raise SystemExit(f"Application crashed due to agent loading failure: {self.module_import_path}")
+
+#     def __load_agents(self):
+#         # Load agents
+#         self.agents = []
+#         loaded_agent_names = set()
+
+#         # Find all agent files recursively
+#         for root, _, files in os.walk(self.module_path):
+#             for file in files:
+#                 if file.endswith("Agent.py") and not file.endswith("Agent_test.py"):
+#                     # Get relative path from module root to agent file
+#                     rel_path = os.path.relpath(root, self.module_path)
+#                     # Convert path to import format
+#                     import_path = rel_path.replace(os.sep, ".")
+#                     if import_path == ".":
+#                         agent_path = self.module_import_path + "." + file[:-3]
+#                     else:
+#                         agent_path = self.module_import_path + "." + import_path + "." + file[:-3]
+
+#                     module = importlib.import_module(agent_path)
+#                     if hasattr(module, "create_agent"):
+#                         agent = module.create_agent()
+#                         if agent is not None:
+#                             agent_name = getattr(agent, "name", None)
+#                             if agent_name and agent_name not in loaded_agent_names:
+#                                 self.agents.append(agent)
+#                                 loaded_agent_names.add(agent_name)
+#                             else:
+#                                 logger.warning(f"Skipping duplicate agent: {agent_name}")
+
+#     def __load_triggers(self):
+#         if os.path.exists(os.path.join(self.module_path, "triggers.py")):
+#             module = importlib.import_module(self.module_import_path + ".triggers")
+#             if hasattr(module, "triggers"):
+#                 self.triggers = module.triggers
+
+#     def __load_ontologies(self):
+#         if os.path.exists(os.path.join(self.module_path, "ontologies")):
+#             for file in glob.glob(
+#                 os.path.join(self.module_path, "ontologies", "**", "*.ttl"),
+#                 recursive=True,
+#             ):
+#                 self.ontologies.append(file)
+
+#     def on_initialized(self):
+#         if hasattr(self.imported_module, "on_initialized"):
+#             self.imported_module.on_initialized()
+#             self.imported_module.on_initialized()

naas_abi_core/module/ModuleAgentLoader.py

@@ -0,0 +1,50 @@
+import importlib
+import os
+from typing import List
+
+from naas_abi_core.module.ModuleUtils import find_class_module_root_path
+from naas_abi_core.services.agent.Agent import Agent
+from naas_abi_core.utils.Logger import logger
+
+
+class ModuleAgentLoader:
+    @classmethod
+    def load_agents(cls, class_: type) -> List[type[Agent]]:
+        agents: List[type[Agent]] = []
+        module_root_path = find_class_module_root_path(class_)
+
+        agents_path = module_root_path / "agents"
+
+        logger.debug(f"Loading agents from {agents_path}")
+
+        if os.path.exists(agents_path):
+            for file in os.listdir(agents_path):
+                if file.endswith(".py") and not file.endswith("test.py"):
+                    agent_module_path = (
+                        f"{class_.__module__}.agents.{file.replace('.py', '')}"
+                    )
+                    logger.debug(f"Importing agent module from {agent_module_path}")
+                    agent_module = importlib.import_module(agent_module_path)
+                    for key, value in agent_module.__dict__.items():
+                        if (
+                            isinstance(value, type)
+                            and issubclass(value, Agent)
+                            and value.__module__.split(".")[0]
+                            == class_.__module__.split(".")[
+                                0
+                            ]  # This makes sure we only load agents from the same module.
+                        ):
+                            if not hasattr(key, "New") and hasattr(
+                                agent_module, "create_agent"
+                            ):
+                                setattr(
+                                    getattr(agent_module, key),
+                                    "New",
+                                    getattr(agent_module, "create_agent"),
+                                )
+
+                            agents.append(getattr(agent_module, key))
+
+        logger.debug(f"Agents: {agents}")
+
+        return agents

naas_abi_core/module/ModuleUtils.py

@@ -0,0 +1,20 @@
+import inspect
+from pathlib import Path
+
+
+def find_class_module_root_path(class_: type) -> Path:
+    class_file_path = inspect.getfile(class_)
+    class_path = Path(class_file_path)
+    class_directory = str(class_path.parent)
+    return Path(class_directory)
+    # logger.debug(f"Class directory: {class_.__module__}")
+    # logger.debug(f"Class file path: {class_directory}")
+    # module_name = class_.__module__.split(".")[0]
+
+    # # find last occurrence of module_name in class_directory
+    # module_root_path = class_directory[
+    #     : class_directory.rfind(module_name) + len(module_name)
+    # ]
+
+    # logger.debug(f"Module root path: {module_root_path}")
+    # return Path(module_root_path)

naas_abi_core/modules/templatablesparqlquery/README.md

@@ -0,0 +1,196 @@
+# Templatable SPARQL Query Module
+
+## Overview
+
+### Description
+
+The Templatable SPARQL Query Module provides a dynamic system for creating reusable SPARQL queries through ontology-based definitions. This module enables developers to define SPARQL query templates in RDF/TTL format with arguments and validation patterns, which are then automatically converted into executable workflows and tools at runtime.
+
+This module enables:
+- Dynamic SPARQL query generation from ontology definitions
+- Automatic argument validation using regex patterns and formats
+- Runtime tool creation for AI agents without writing Python boilerplate
+- Template-based query execution using Jinja2 syntax
+- Integration with knowledge graphs and triple stores
+
+### Requirements
+
+Triple Store Setup:
+1. Ensure you have a running triple store service configured in your ABI instance
+2. The module uses `services.triple_store_service` to query ontology definitions
+
+### TL;DR
+
+To get started with the Templatable SPARQL Query module:
+
+1. Define your SPARQL queries in TTL format using the provided ontology
+2. Load the TTL file into your triple store
+3. The module automatically creates tools from your query definitions
+
+Access tools using:
+```python
+from src.core.modules.templatablesparqlquery import get_tools
+tools = get_tools()
+```
+
+### Structure
+
+```
+src/core/templatablesparqlquery/
+
+├── ontologies/                         
+│   └── TemplatableSparqlQueryOntology.ttl
+├── workflows/                     
+│   ├── GenericWorkflow.py          
+│   └── TemplatableSparqlQuery.py           
+└── README.md                       
+```
+
+## Core Components
+
+The module provides a declarative approach to SPARQL query definition and execution through ontology-based configuration.
+
+### Workflows
+
+#### Templatable SPARQL Query Workflow
+Dynamically loads query definitions from the triple store and creates executable workflows with proper argument validation and Jinja2 template rendering.
+
+**Capabilities:**
+- Loads query definitions from triple store using SPARQL
+- Creates Pydantic models for argument validation
+- Renders SPARQL templates with user parameters
+- Executes queries against the triple store
+- Returns formatted results
+
+**Use Cases:**
+- Dynamic query generation without hardcoded Python workflows
+- Reusable query templates with parameter validation
+- AI agent tool creation from ontology definitions
+
+#### Generic Workflow
+A generic wrapper class that handles the execution of templated SPARQL queries with type-safe argument validation.
+
+**Configuration:**
+
+```python
+from src.core.modules.templatablesparqlquery.workflows.GenericWorkflow import GenericWorkflow
+from pydantic import BaseModel, Field
+
+# Define argument model
+class MyQueryArguments(BaseModel):
+    department_id: str = Field(..., description="Department identifier", pattern="^[A-Z0-9]{3,}$")
+    employee_name: str = Field(..., description="Employee name filter")
+
+# Create workflow
+workflow = GenericWorkflow[MyQueryArguments](
+    name="find_employees",
+    description="Find employees in a department",
+    sparql_template=sparql_query_template,
+    arguments_model=MyQueryArguments
+)
+```
+
+#### Run
+Execute workflows by calling the module's tool loading functions:
+```python
+from src.core.modules.templatablesparqlquery import get_tools
+tools = get_tools()
+# Tools are automatically created from ontology definitions
+```
+
+#### Testing
+Currently no dedicated test files are present in the module structure.
+
+### Ontologies
+
+#### Templatable SPARQL Query Ontology
+
+The core ontology defining the structure for templatable SPARQL queries and their arguments:
+
+**Key Classes:**
+- `abi:TemplatableSparqlQuery`: Represents a SPARQL query template with intent information
+- `abi:QueryArgument`: Represents an argument for query templating
+
+**Key Properties:**
+- `abi:intentDescription`: Natural language description of query purpose
+- `abi:sparqlTemplate`: The SPARQL query template with Jinja2 variables
+- `abi:hasArgument`: Links queries to their arguments
+- `abi:argumentName`: Argument name used in templates
+- `abi:validationPattern`: Regex pattern for argument validation
+- `abi:validationFormat`: Expected format description
+
+#### Example Query Definition
+
+```turtle
+@prefix abi: <http://ontology.naas.ai/abi/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+abi:findEmployeesQuery a abi:TemplatableSparqlQuery ;
+    rdfs:label "Find Employees"@en ;
+    abi:intentDescription "Find all employees working in a specific department" ;
+    abi:sparqlTemplate """
+        SELECT ?employee ?name
+        WHERE {
+            ?employee :worksIn :{{ department_id }} ;
+                    :hasName ?name .
+            {% if employee_name %}
+            FILTER(CONTAINS(LCASE(?name), LCASE("{{ employee_name }}")))
+            {% endif %}
+        }
+    """ ;
+    abi:hasArgument abi:departmentArg .
+
+abi:departmentArg a abi:QueryArgument ;
+    abi:argumentName "department_id" ;
+    abi:argumentDescription "The unique identifier of the department" ;
+    abi:validationPattern "^[A-Z0-9]{3,}$" ;
+    abi:validationFormat "department_id" .
+```
+
+## How to Add New Queries
+
+### Step 1: Define Query in TTL Format
+Create or update a TTL file with your query definition using the templatable SPARQL query ontology.
+
+### Step 2: Define Arguments
+Specify all required arguments with proper validation patterns and descriptions.
+
+### Step 3: Load into Triple Store
+Ensure your TTL file is loaded into the triple store during application initialization.
+
+### Step 4: Access Generated Tools
+The module automatically creates tools from your definitions:
+
+```python
+from src.core.modules.templatablesparqlquery import get_tools
+tools = get_tools()
+```
+
+## Dependencies
+
+### Python Libraries
+- `pydantic`: Data validation and serialization for argument models
+- `rdflib`: RDF graph processing and SPARQL query execution
+- `jinja2`: Template rendering for SPARQL queries
+- `langchain_core`: Tool integration for AI agents
+- `asyncio`: Asynchronous processing support
+
+### Internal Modules
+- `src.utils.SPARQL`: SPARQL result processing utilities
+- `src.services`: Triple store service integration
+
+### External Services
+- **Triple Store**: Required for storing and querying ontology definitions
+- **Knowledge Graph**: Source data for SPARQL query execution
+
+## Technical Implementation
+
+The module uses a sophisticated runtime generation process:
+
+1. **Query Discovery**: Scans the triple store for `TemplatableSparqlQuery` instances
+2. **Argument Resolution**: Retrieves associated `QueryArgument` definitions
+3. **Model Generation**: Creates Pydantic models with validation patterns
+4. **Tool Creation**: Generates LangChain tools for AI agent integration
+5. **Template Execution**: Uses Jinja2 to render SPARQL templates with parameters
+
+This approach eliminates the need for writing repetitive Python code for similar query patterns, allowing developers to focus on query logic and ontology design.

naas_abi_core/modules/templatablesparqlquery/__init__.py

@@ -0,0 +1,39 @@
+from naas_abi_core.module.Module import (
+    BaseModule,
+    ModuleConfiguration,
+    ModuleDependencies,
+)
+from naas_abi_core.modules.templatablesparqlquery.workflows.TemplatableSparqlQueryLoader import (
+    TemplatableSparqlQueryLoader,
+)
+from naas_abi_core.services.triple_store.TripleStoreService import TripleStoreService
+
+
+class ABIModule(BaseModule):
+    __workflows: list = []
+    __tools: list = []
+
+    dependencies: ModuleDependencies = ModuleDependencies(
+        modules=[], services=[TripleStoreService]
+    )
+
+    class Configuration(ModuleConfiguration):
+        pass
+
+    def on_initialized(self):
+        self.__templatable_sparql_query_loader = TemplatableSparqlQueryLoader(
+            self.engine.services.triple_store
+        )
+        self.__workflows = self.__templatable_sparql_query_loader.load_workflows()
+        self.__tools = [
+            tool for workflow in self.__workflows for tool in workflow.as_tools()
+        ]
+
+    def get_workflows(self):
+        return self.__workflows
+
+    def get_tools(self, tool_names: list[str] = []):
+        if len(tool_names) == 0:
+            return self.__tools
+        else:
+            return [tool for tool in self.__tools if tool.name in tool_names]

naas_abi_core/modules/templatablesparqlquery/ontologies/TemplatableSparqlQueryOntology.ttl

@@ -0,0 +1,116 @@
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix dc11: <http://purl.org/dc/elements/1.1/> .
+@prefix dc: <http://purl.org/dc/terms/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@prefix bfo: <http://purl.obolibrary.org/obo/> .
+@prefix cco: <https://www.commoncoreontologies.org/> .
+@prefix abi: <http://ontology.naas.ai/abi/> .
+
+<http://ontology.naas.ai/abi/TemplatableSparqlQueryOntology> a owl:Ontology ;
+    owl:versionIRI <https://github.com/jupyter-naas/abi/tree/cli/src/core/modules/abi/ontologies/domain-level/TemplatableSparqlQueryOntology.ttl> ;
+    dc11:contributor "Jeremy Ravenel" , "Maxime Jublou" , "Florent Ravenel" ;
+    dc:description "Templatable Sparql Query Ontology."@en ;
+    dc:license "" ;
+    dc:title "Templatable Sparql Query Ontology" .
+
+#################################################################
+#    Classes
+#################################################################
+
+abi:TemplatableSparqlQuery a owl:Class ;
+    rdfs:subClassOf bfo:BFO_0000031 ;
+    rdfs:label "Templatable SPARQL Query"@en ;
+    rdfs:comment "A class representing a SPARQL query that can be templated with variables and includes intent information."@en .
+
+abi:QueryArgument a owl:Class ;
+    rdfs:subClassOf bfo:BFO_0000031 ;
+    rdfs:label "Query Argument"@en ;
+    rdfs:comment "A class representing an argument that can be used to template a SPARQL query."@en .
+
+#################################################################
+#    Object Properties
+#################################################################
+
+abi:hasArgument a owl:ObjectProperty ;
+    rdfs:label "has argument"@en ;
+    rdfs:domain abi:TemplatableSparqlQuery ;
+    rdfs:range abi:QueryArgument ;
+    rdfs:comment "Links a templatable SPARQL query to its arguments."@en .
+
+#################################################################
+#    Data Properties
+#################################################################
+
+abi:intentDescription a owl:DatatypeProperty ;
+    rdfs:label "intent description"@en ;
+    rdfs:domain abi:TemplatableSparqlQuery ;
+    rdfs:range xsd:string ;
+    rdfs:comment "A natural language description of the query's intent."@en .
+
+abi:sparqlTemplate a owl:DatatypeProperty ;
+    rdfs:label "SPARQL template"@en ;
+    rdfs:domain abi:TemplatableSparqlQuery ;
+    rdfs:range xsd:string ;
+    rdfs:comment "The SPARQL query template with variable placeholders."@en .
+
+abi:argumentName a owl:DatatypeProperty ;
+    rdfs:label "argument name"@en ;
+    rdfs:domain abi:QueryArgument ;
+    rdfs:range xsd:string ;
+    rdfs:comment "The name of the argument used in the template."@en .
+
+abi:argumentDescription a owl:DatatypeProperty ;
+    rdfs:label "argument description"@en ;
+    rdfs:domain abi:QueryArgument ;
+    rdfs:range xsd:string ;
+    rdfs:comment "A description of what the argument represents."@en .
+
+abi:validationPattern a owl:DatatypeProperty ;
+    rdfs:label "validation pattern"@en ;
+    rdfs:domain abi:QueryArgument ;
+    rdfs:range xsd:string ;
+    rdfs:comment "A regex pattern for validating the argument value."@en .
+
+abi:validationFormat a owl:DatatypeProperty ;
+    rdfs:label "validation format"@en ;
+    rdfs:domain abi:QueryArgument ;
+    rdfs:range xsd:string ;
+    rdfs:comment "The expected format of the argument value (e.g., date, number, URI)."@en .
+
+#################################################################
+#    Example Usage
+#################################################################
+
+# # Example of a query to find employees in a department with optional name filter:
+# abi:findEmployeesQuery a abi:TemplatableSparqlQuery ;
+#     rdfs:label "findEmployeesQuery"@en ;
+#     abi:intentDescription "Find all employees working in a specific department, optionally filtered by name" ;
+#     abi:sparqlTemplate """
+#         SELECT ?employee ?name
+#         WHERE {
+#             ?employee :worksIn :{{ department_id }} ;
+#                     :hasName ?name .
+#             {% if employee_name %}
+#             FILTER(CONTAINS(LCASE(?name), LCASE("{{ employee_name }}")))
+#             {% endif %}
+#         }
+#     """ ;
+#     abi:hasArgument abi:departmentArg, abi:nameArg .
+
+# abi:departmentArg a abi:QueryArgument ;
+#     abi:argumentName "department_id" ;
+#     abi:argumentDescription "The unique identifier of the department" ;
+#     abi:validationPattern "^[A-Z0-9]{3,}$" ;
+#     abi:validationFormat "department_id" .
+
+# abi:nameArg a abi:QueryArgument ;
+#     abi:argumentName "employee_name" ;
+#     abi:argumentDescription "Optional name to filter employees (case-insensitive partial match)" ;
+#     abi:validationPattern "^[a-zA-Z0-9\\s-]{2,50}$" ;
+#     abi:validationFormat "employee_name" .
+
+# #################################################################
+