Merge branch 'main' of github.com:jupyter-naas/abi

Author: Dr0p42

bandit.yaml

@@ -19,3 +19,5 @@ skips:
   # hashlib/md5 — flagged generically; project uses it for non-security hashing (e.g. cache keys)
   # Remove this skip once all hashlib usages have been audited and confirmed safe
   - B324
+  # pickle used only with trusted internal storage
+  - B301

libs/naas-abi-core/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v1.47.0 (2026-05-26)
+
+### Documentation
+
+- **event**: Add README covering event creation, publish/subscribe, query, and filter DSL
+  ([`64ad241`](https://github.com/jupyter-naas/abi/commit/64ad241d40b77114c7e70eefe52387ec30afe616))
+
+
 ## v1.46.0 (2026-05-26)
 
 ### Features

libs/naas-abi-core/naas_abi_core/services/event/README.md

@@ -23,7 +23,11 @@ The contract `EventService` cares about:
 
 ### 1. Write a TTL
 
-Create a `.ttl` file in your domain's `ontologies/modules/` directory. The two things that matter: an `owl:imports` pointing at the EventOntology TTL, and a `rdfs:subClassOf abi:LogProcess` on each event class.
+Create a `.ttl` file in your domain's `ontologies/modules/` directory. Three things matter:
+
+1. `owl:imports <http://ontology.naas.ai/abi/EventService>` so `LogProcess` is pulled from the canonical EventOntology (not regenerated locally).
+2. `rdfs:subClassOf abi:LogProcess` on each event class.
+3. The `abi:pythonPackage` / `abi:ontologyResource` / `abi:pythonResource` locator annotations on your own `owl:Ontology` declaration, so any *other* module can in turn `owl:imports` your ontology by its canonical IRI.
 
 ```ttl
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@@ -37,7 +41,10 @@ Create a `.ttl` file in your domain's `ontologies/modules/` directory. The two t
 
 mydomain:MyDomainEvents a owl:Ontology ;
   dc:title "My domain events"@en ;
-  owl:imports <python://naas_abi_core.services.event.ontologies.modules/EventOntology.ttl> .
+  owl:imports <http://ontology.naas.ai/abi/EventService> ;
+  abi:pythonPackage    "my_module" ;
+  abi:ontologyResource "ontologies/modules/MyDomainEvents.ttl" ;
+  abi:pythonResource   "ontologies/modules/MyDomainEvents.py" .
 
 mydomain:UserRegistered a owl:Class ;
     rdfs:label "UserRegistered"@en ;
@@ -55,7 +62,7 @@ mydomain:source a owl:DatatypeProperty ;
     rdfs:range xsd:string .
 ```
 
-**Why `python://`?** It's an `importlib.resources`-based locator that works the same in editable installs, wheels, and zipped packages — it doesn't break the moment your TTL lives inside a `.venv`. Plain relative paths (e.g. `<../other/Foo.ttl>`) also work for intra-package references. Remote HTTP IRIs (BFO, etc.) are deliberately skipped — they're RDF-level references, not codegen inputs.
+**Why `<http://ontology.naas.ai/abi/EventService>`?** That's the canonical IRI of the EventOntology — a normal, spec-compliant `owl:imports` target. onto2py keeps an index of every ontology declared by an installed `naas_abi*` package; when an `owl:imports` IRI matches one in the index, the TTL is loaded through `importlib.resources` (via the `abi:pythonPackage` / `abi:ontologyResource` annotations on that ontology), so it works the same in editable installs, wheels, and zipped packages. Plain relative paths (e.g. `<../other/Foo.ttl>`) also work for intra-package references. Remote HTTP IRIs that no installed package declares (BFO, etc.) are skipped — they're RDF-level references, not codegen inputs.
 
 ### 2. Generate the Python module
 

libs/naas-abi-core/naas_abi_core/services/event/ontologies/modules/EventOntology.ttl

@@ -8,11 +8,30 @@
 @prefix bfo: <http://purl.obolibrary.org/obo/> .
 @prefix abi: <http://ontology.naas.ai/abi/> .
 
+# Locator annotations: tell onto2py where this ontology lives in the Python
+# package tree so downstream ontologies can import it by its canonical IRI
+# (a spec-compliant owl:imports target) and still resolve correctly inside
+# editable installs, wheels, and zipped packages.
+abi:pythonPackage a owl:AnnotationProperty ;
+  rdfs:label "python package"@en ;
+  rdfs:comment "Dotted Python package used as the importlib.resources root for this ontology's files."@en .
+
+abi:ontologyResource a owl:AnnotationProperty ;
+  rdfs:label "ontology resource"@en ;
+  rdfs:comment "Path to this ontology's .ttl file, relative to abi:pythonPackage."@en .
+
+abi:pythonResource a owl:AnnotationProperty ;
+  rdfs:label "python resource"@en ;
+  rdfs:comment "Path to this ontology's generated .py file, relative to abi:pythonPackage. Used to build the dotted module for `from <module> import <Class>`."@en .
+
 abi:EventService a owl:Ontology ;
   dc:title "Event Service Ontology"@en ;
   dc:description "Base ontology for engine events. Defines LogProcess as the root class for all events published through the EventService."@en ;
   dc:license <https://creativecommons.org/licenses/by/4.0/> ;
   rdfs:comment "All event types published through the EventService must be rdfs:subClassOf abi:LogProcess." ;
+  abi:pythonPackage "naas_abi_core.services.event" ;
+  abi:ontologyResource "ontologies/modules/EventOntology.ttl" ;
+  abi:pythonResource "ontologies/modules/EventOntology.py" ;
   dc11:date "2026-05-22"^^xsd:date .
 
 # Reference: BFO Process (parent class — included for the generator to resolve the hierarchy).

libs/naas-abi-core/naas_abi_core/services/object_storage/ontologies/modules/ObjectStorageEventOntology.py

@@ -15,13 +15,12 @@
     get_origin,
 )
 
-from pydantic import BaseModel, Field, ValidationError
-from rdflib import Graph, Literal, Namespace, URIRef
-from rdflib.namespace import OWL, RDF, RDFS, XSD
-
 from naas_abi_core.services.event.ontologies.modules.EventOntology import (
     LogProcess,
 )
+from pydantic import BaseModel, Field, ValidationError
+from rdflib import Graph, Literal, Namespace, URIRef
+from rdflib.namespace import OWL, RDF, RDFS, XSD
 
 BFO = Namespace("http://purl.obolibrary.org/obo/")
 ABI = Namespace("http://ontology.naas.ai/abi/")

libs/naas-abi-core/naas_abi_core/services/object_storage/ontologies/modules/ObjectStorageEventOntology.ttl

@@ -12,7 +12,10 @@ os:ObjectStorageEventOntology a owl:Ontology ;
   dc:title "Object Storage Event Ontology"@en ;
   dc:description "Events emitted by the ObjectStorageService when objects are written to or removed from the store."@en ;
   dc:license <https://creativecommons.org/licenses/by/4.0/> ;
-  owl:imports <python://naas_abi_core.services.event.ontologies.modules/EventOntology.ttl> ;
+  owl:imports <http://ontology.naas.ai/abi/EventService> ;
+  abi:pythonPackage    "naas_abi_core.services.object_storage" ;
+  abi:ontologyResource "ontologies/modules/ObjectStorageEventOntology.ttl" ;
+  abi:pythonResource   "ontologies/modules/ObjectStorageEventOntology.py" ;
   dc11:date "2026-05-26"^^xsd:date .
 
 # ObjectPut: published after ObjectStorageService.put_object() succeeds.

libs/naas-abi-core/naas_abi_core/utils/StorageUtils.py

@@ -1,7 +1,8 @@
 import json
+import pickle
 from datetime import datetime
 from io import BytesIO
-from typing import Dict, Tuple
+from typing import Any, Dict, Tuple
 
 import pandas as pd
 import yaml
@@ -465,3 +466,41 @@ def save_powerpoint_presentation(
         except Exception as e:
             logger.error(f"Error saving PowerPoint presentation to {dir_path}: {e}")
             return dir_path, file_name
+
+    def get_pickle(self, dir_path: str, file_name: str) -> Any | None:
+        """
+        Get a pickled Python object from storage.
+
+        SECURITY: ``pickle.loads`` will execute arbitrary code embedded in
+        the byte stream. Only call this on objects written by trusted
+        producers in the same trust boundary.
+        """
+        try:
+            content = self.__storage_service.get_object(dir_path, file_name)
+            if content is None:
+                return None
+            return pickle.loads(content)  # nosec B301 — trusted internal storage only
+        except Exception as e:
+            logger.warning(f"Error getting pickle from {dir_path}/{file_name}: {e}")
+            return None
+
+    def save_pickle(
+        self, obj: Any, dir_path: str, file_name: str, copy: bool = True
+    ) -> Tuple[str, str]:
+        """
+        Pickle a Python object and save it to storage.
+        """
+        try:
+            content = pickle.dumps(obj)
+            self.__storage_service.put_object(
+                prefix=dir_path, key=file_name, content=content
+            )
+            if copy:
+                self.__make_copy(dir_path, file_name, content)
+            logger.debug(
+                f"[save_pickle] File successfully written to storage: {dir_path}/{file_name}"
+            )
+            return dir_path, file_name
+        except Exception as e:
+            logger.error(f"Error saving pickle to {dir_path}: {e}")
+            return dir_path, file_name