admina-framework 0.9.0__py3-none-any.whl

admina/plugins/builtin/compliance/eu_ai_act.py

@@ -0,0 +1,202 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — EU AI Act compliance template plugin.
+
+Loads requirements from ``eu_ai_act.yaml`` and implements the
+:class:`BaseComplianceTemplate` interface for risk classification
+and gap analysis.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml  # PyYAML — already a core dependency
+
+from admina.plugins.base import BaseComplianceTemplate
+
+logger = logging.getLogger("admina.plugins.compliance.eu_ai_act")
+
+_YAML_PATH = Path(__file__).parent / "eu_ai_act.yaml"
+
+# Keywords used for risk classification (kept in code for performance)
+_UNACCEPTABLE_KW = [
+    "social scoring",
+    "social credit",
+    "real-time biometric",
+    "mass surveillance",
+    "subliminal manipulation",
+]
+_HIGH_RISK_KW = [
+    "credit scor",
+    "recruitment",
+    "hiring",
+    "law enforcement",
+    "critical infrastructure",
+    "healthcare",
+    "medical",
+    "education",
+    "migration",
+    "border",
+    "judicial",
+    "biometric",
+    "financial",
+    "trading",
+    "insurance",
+]
+_SENSITIVE_DATA = {"health", "biometric", "financial", "criminal", "genetic"}
+_LIMITED_KW = [
+    "chatbot",
+    "conversational",
+    "content generation",
+    "emotion recognition",
+    "deepfake",
+    "synthetic media",
+]
+
+
+class EUAIActComplianceTemplate(BaseComplianceTemplate):
+    """Compliance template for the EU AI Act.
+
+    Loads structured requirements from the bundled YAML file and
+    provides risk classification and gap analysis.
+    """
+
+    def __init__(self) -> None:
+        self._data = self._load_yaml()
+
+    @staticmethod
+    def _load_yaml() -> dict:
+        """Load the bundled YAML requirements file."""
+        try:
+            return yaml.safe_load(_YAML_PATH.read_text(encoding="utf-8")) or {}
+        except (OSError, ValueError) as exc:
+            logger.warning("Failed to load EU AI Act YAML: %s", exc)
+            return {}
+
+    # ── BaseComplianceTemplate interface ────────────────────────
+
+    def get_requirements(self) -> list[dict]:
+        """Return the list of EU AI Act requirements.
+
+        Returns:
+            List of ``{"id": str, "title": str, "article": str,
+            "checks": list[str]}``.
+        """
+        reqs: list[dict] = []
+        for req_id, req_info in self._data.get("requirements", {}).items():
+            reqs.append(
+                {
+                    "id": req_id,
+                    "title": req_info["name"],
+                    "article": req_info["article"],
+                    "checks": req_info["checks"],
+                }
+            )
+        return reqs
+
+    def evaluate(self, governance_state: dict) -> dict:
+        """Evaluate current governance state against EU AI Act.
+
+        Args:
+            governance_state: A dict with:
+                - ``risk_category`` (str): the classified risk level.
+                - ``current_compliance`` (dict[str, list[bool]]): check results.
+
+        Returns:
+            ``{"score": float, "gaps": list, "covered": list,
+            "enforcement_deadline": str}``.
+        """
+        risk = governance_state.get("risk_category", "minimal")
+        compliance = governance_state.get("current_compliance", {})
+
+        if risk not in ("high", "unacceptable"):
+            return {
+                "score": 1.0,
+                "gaps": [],
+                "covered": [],
+                "enforcement_deadline": self._data.get("enforcement_deadline", "2027-12-02"),
+            }
+
+        gaps: list[dict] = []
+        covered: list[dict] = []
+        total = 0
+        passed = 0
+
+        for req_id, req_info in self._data.get("requirements", {}).items():
+            checks = compliance.get(req_id, [False] * len(req_info["checks"]))
+            for check_desc, is_met in zip(req_info["checks"], checks):
+                total += 1
+                entry = {
+                    "requirement": req_info["name"],
+                    "article": req_info["article"],
+                    "check": check_desc,
+                }
+                if is_met:
+                    passed += 1
+                    covered.append(entry)
+                else:
+                    gaps.append(entry)
+
+        score = round(passed / max(total, 1), 4)
+
+        return {
+            "score": score,
+            "gaps": gaps,
+            "covered": covered,
+            "total_checks": total,
+            "passed_checks": passed,
+            "enforcement_deadline": self._data.get("enforcement_deadline", "2027-12-02"),
+            "assessed_at": datetime.now(UTC).isoformat(),
+        }
+
+    @property
+    def framework_name(self) -> str:
+        """Framework name."""
+        return "EU AI Act"
+
+    # ── Extra utility (not part of ABC) ─────────────────────────
+
+    def classify_risk(
+        self,
+        system_description: str,
+        use_case: str,
+        data_types: list[str] | None = None,
+    ) -> str:
+        """Classify an AI system's risk under the EU AI Act.
+
+        Returns:
+            One of ``"unacceptable"``, ``"high"``, ``"limited"``, ``"minimal"``.
+        """
+        desc = system_description.lower()
+        uc = use_case.lower()
+
+        if any(kw in desc or kw in uc for kw in _UNACCEPTABLE_KW):
+            return "unacceptable"
+
+        score = 0
+        if any(kw in desc or kw in uc for kw in _HIGH_RISK_KW):
+            score += 2
+        if data_types and any(d.lower() in _SENSITIVE_DATA for d in data_types):
+            score += 1
+        if score >= 2:
+            return "high"
+
+        if any(kw in desc or kw in uc for kw in _LIMITED_KW):
+            return "limited"
+
+        return "minimal"

admina/plugins/builtin/connectors/__init__.py

@@ -0,0 +1,14 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+

admina/plugins/builtin/connectors/chromadb.py

@@ -0,0 +1,137 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — ChromaDB data connector.
+
+Wraps the ``chromadb`` Python client for vector-store operations.
+
+Requires: ``pip install chromadb``  (optional dependency).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from admina.plugins.base import BaseDataConnector
+
+logger = logging.getLogger("admina.plugins.connectors.chromadb")
+
+
+class ChromaDBConnector(BaseDataConnector):
+    """Data connector for ChromaDB vector store.
+
+    Args:
+        host: ChromaDB server host.
+        port: ChromaDB server port.
+        collection_name: Default collection to operate on.
+    """
+
+    def __init__(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        collection_name: str | None = None,
+    ) -> None:
+        self._host = host or os.environ.get("ADMINA_CHROMA_HOST", "localhost")
+        self._port = port if port is not None else int(os.environ.get("ADMINA_CHROMA_PORT", "8000"))
+        self._collection_name = collection_name or os.environ.get(
+            "ADMINA_CHROMA_COLLECTION", "admina_default"
+        )
+        self._client: Any = None
+        self._collection: Any = None
+
+    def _get_collection(self) -> Any:
+        """Lazily initialise the ChromaDB client and collection."""
+        if self._collection is None:
+            try:
+                import chromadb  # type: ignore[import-untyped]
+
+                self._client = chromadb.HttpClient(host=self._host, port=self._port)
+                self._collection = self._client.get_or_create_collection(name=self._collection_name)
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'chromadb' package is required for ChromaDBConnector. "
+                    "Install it with: pip install chromadb"
+                ) from exc
+        return self._collection
+
+    # ── BaseDataConnector interface ─────────────────────────────
+
+    async def ingest(self, source: Any, **kwargs: Any) -> dict:
+        """Ingest documents into ChromaDB.
+
+        Args:
+            source: A list of dicts, each with ``"id"``, ``"text"``, and
+                optional ``"metadata"``.
+            **kwargs: Extra options (``collection_name``, etc.).
+
+        Returns:
+            ``{"doc_count": int, "chunk_count": int, "collection": str}``.
+        """
+        collection = self._get_collection()
+
+        if isinstance(source, list):
+            docs = source
+        else:
+            docs = [{"id": "doc_0", "text": str(source)}]
+
+        ids = [d.get("id", f"doc_{i}") for i, d in enumerate(docs)]
+        documents = [d.get("text", str(d)) for d in docs]
+        metadatas = [d.get("metadata", {}) for d in docs]
+
+        collection.add(ids=ids, documents=documents, metadatas=metadatas)
+
+        return {
+            "doc_count": len(docs),
+            "chunk_count": len(docs),
+            "collection": self._collection_name,
+        }
+
+    async def query(self, query: str, **kwargs: Any) -> list[dict]:
+        """Query ChromaDB for similar documents.
+
+        Args:
+            query: Search query string.
+            **kwargs: Supports ``top_k`` (default 5).
+
+        Returns:
+            Ranked list of ``{"text": str, "metadata": dict, "score": float}``.
+        """
+        collection = self._get_collection()
+        top_k = kwargs.get("top_k", 5)
+
+        results = collection.query(query_texts=[query], n_results=top_k)
+
+        output: list[dict] = []
+        documents = results.get("documents", [[]])[0]
+        metadatas = results.get("metadatas", [[]])[0]
+        distances = results.get("distances", [[]])[0]
+
+        for text, meta, dist in zip(documents, metadatas, distances):
+            output.append(
+                {
+                    "text": text,
+                    "metadata": meta or {},
+                    "score": round(1.0 / (1.0 + dist), 4),
+                }
+            )
+
+        return output
+
+    @property
+    def name(self) -> str:
+        """Connector name."""
+        return "chromadb"

admina/plugins/builtin/connectors/filesystem.py

@@ -0,0 +1,111 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — Filesystem data connector.
+
+A simple data connector that reads files from the local filesystem.
+Useful as a zero-dependency fallback and for development.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from admina.plugins.base import BaseDataConnector
+
+logger = logging.getLogger("admina.plugins.connectors.filesystem")
+
+
+class FilesystemConnector(BaseDataConnector):
+    """Data connector that reads plain-text files from a directory.
+
+    Args:
+        base_dir: Root directory for file operations.
+    """
+
+    def __init__(self, base_dir: str = ".") -> None:
+        self._base_dir = Path(base_dir).resolve()
+
+    # ── BaseDataConnector interface ─────────────────────────────
+
+    async def ingest(self, source: Any, **kwargs: Any) -> dict:
+        """Read files from *source* path(s).
+
+        Args:
+            source: A file path, directory path, or list of file paths.
+            **kwargs: Supports ``glob`` pattern (default ``"*"``) when
+                *source* is a directory.
+
+        Returns:
+            ``{"doc_count": int, "chunk_count": int}``.
+        """
+        paths: list[Path] = []
+        if isinstance(source, (list, tuple)):
+            paths = [Path(p) for p in source]
+        else:
+            p = Path(source)
+            if p.is_dir():
+                pattern = kwargs.get("glob", "*")
+                paths = list(p.glob(pattern))
+            else:
+                paths = [p]
+
+        chunk_count = 0
+        for fp in paths:
+            if fp.is_file():
+                chunk_count += 1
+
+        return {"doc_count": len(paths), "chunk_count": chunk_count}
+
+    async def query(self, query: str, **kwargs: Any) -> list[dict]:
+        """Search files in the base directory for *query*.
+
+        A naive substring search — production use should prefer a
+        vector store connector like ChromaDB.
+
+        Args:
+            query: Search string.
+            **kwargs: Supports ``glob`` pattern (default ``"**/*"``).
+
+        Returns:
+            List of matching files with content excerpts.
+        """
+        pattern = kwargs.get("glob", "**/*")
+        results: list[dict] = []
+
+        for fp in self._base_dir.glob(pattern):
+            if not fp.is_file():
+                continue
+            try:
+                text = fp.read_text(errors="replace")
+            except OSError:
+                continue
+
+            if query.lower() in text.lower():
+                results.append(
+                    {
+                        "text": text[:500],
+                        "metadata": {"path": str(fp)},
+                        "score": 1.0,
+                    }
+                )
+
+        return results
+
+    @property
+    def name(self) -> str:
+        """Connector name."""
+        return "filesystem"

admina/plugins/builtin/forensic/__init__.py

@@ -0,0 +1,14 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+

admina/plugins/builtin/forensic/filesystem.py

@@ -0,0 +1,163 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — Filesystem forensic store plugin.
+
+A zero-dependency fallback forensic store that writes JSON records to
+the local filesystem.  Suitable for development, testing, and
+single-node deployments where S3/MinIO is not available.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from admina.plugins.base import BaseForensicStore
+
+logger = logging.getLogger("admina.plugins.forensic.filesystem")
+
+
+class FilesystemForensicStore(BaseForensicStore):
+    """Forensic store backed by local JSON files.
+
+    Args:
+        base_dir: Directory to store forensic records.
+    """
+
+    def __init__(self, base_dir: str = ".admina/forensic") -> None:
+        self._base_dir = Path(base_dir).resolve()
+        self._base_dir.mkdir(parents=True, exist_ok=True)
+        self._chain_head: str = "GENESIS"
+        self._record_count: int = 0
+        self._restore_chain_state()
+
+    # ── BaseForensicStore interface ─────────────────────────────
+
+    async def append(self, record: dict) -> str:
+        """Write a governance record to a local JSON file.
+
+        Args:
+            record: The governance event dict.
+
+        Returns:
+            The SHA-256 hash of the stored record.
+        """
+        self._record_count += 1
+
+        forensic_record = {
+            "sequence_number": self._record_count,
+            "timestamp_utc": datetime.now(UTC).isoformat(),
+            "timestamp_unix_ms": int(time.time() * 1000),
+            "previous_hash": self._chain_head,
+            "event": record,
+        }
+
+        record_json = json.dumps(forensic_record, sort_keys=True, default=str)
+        record_hash = hashlib.sha256(record_json.encode("utf-8")).hexdigest()
+        forensic_record["record_hash"] = record_hash
+        self._chain_head = record_hash
+
+        # Write record file
+        record_file = self._base_dir / f"{self._record_count:08d}.json"
+        record_file.write_text(
+            json.dumps(forensic_record, indent=2, default=str),
+            encoding="utf-8",
+        )
+
+        self._persist_chain_state()
+        return record_hash
+
+    async def verify_chain(self, last_n: int = 0) -> dict:
+        """Verify hash-chain integrity by re-reading stored records.
+
+        Args:
+            last_n: If > 0, verify only the last *n* records.
+
+        Returns:
+            ``{"valid": bool, "records": int, "last_hash": str}``.
+        """
+        files = sorted(self._base_dir.glob("[0-9]*.json"))
+        if last_n > 0:
+            files = files[-last_n:]
+
+        prev_hash: str | None = None
+        for fp in files:
+            try:
+                rec = json.loads(fp.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                return {"valid": False, "records": 0, "last_hash": ""}
+
+            if prev_hash is not None and rec.get("previous_hash") != prev_hash:
+                return {
+                    "valid": False,
+                    "records": self._record_count,
+                    "last_hash": self._chain_head,
+                }
+
+            # Recompute hash to verify integrity
+            stored_hash = rec.pop("record_hash", "")
+            recomputed = hashlib.sha256(
+                json.dumps(rec, sort_keys=True, default=str).encode("utf-8")
+            ).hexdigest()
+            if recomputed != stored_hash:
+                return {
+                    "valid": False,
+                    "records": self._record_count,
+                    "last_hash": self._chain_head,
+                }
+            prev_hash = stored_hash
+
+        return {
+            "valid": True,
+            "records": self._record_count,
+            "last_hash": self._chain_head,
+        }
+
+    @property
+    def store_name(self) -> str:
+        """Store name."""
+        return "filesystem"
+
+    # ── Internal helpers ────────────────────────────────────────
+
+    def _restore_chain_state(self) -> None:
+        """Restore chain state from the state file on startup."""
+        state_file = self._base_dir / "_chain_state.json"
+        if state_file.exists():
+            try:
+                state = json.loads(state_file.read_text(encoding="utf-8"))
+                self._chain_head = state.get("chain_head", "GENESIS")
+                self._record_count = state.get("record_count", 0)
+            except (OSError, json.JSONDecodeError):
+                pass
+
+    def _persist_chain_state(self) -> None:
+        """Persist chain state to a JSON file."""
+        state_file = self._base_dir / "_chain_state.json"
+        state_file.write_text(
+            json.dumps(
+                {
+                    "chain_head": self._chain_head,
+                    "record_count": self._record_count,
+                    "updated_at": datetime.now(UTC).isoformat(),
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )