admina-framework 0.9.0__py3-none-any.whl

admina/proxy/multi_upstream.py

@@ -0,0 +1,156 @@
+# 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 — Multi-Upstream MCP Router
+Routes MCP calls to correct upstream servers. Enables OpenClaw integration.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger("admina.router")
+
+
+@dataclass
+class ServerRoute:
+    """A registered upstream MCP server."""
+
+    name: str
+    upstream_url: str = ""
+    server_type: str = "sse"  # sse | http | stdio
+    proxy_mode: str = "transparent"  # transparent | stdio_wrap
+    headers: dict = field(default_factory=dict)
+    tool_names: list = field(default_factory=list)  # tools this server provides
+    healthy: bool = True
+    request_count: int = 0
+    block_count: int = 0
+
+
+class MultiUpstreamRouter:
+    """
+    Manages routing to multiple MCP upstream servers.
+
+    Loading:
+      router = MultiUpstreamRouter()
+      router.load_config("/app/routing.json")
+
+    Routing:
+      route = router.resolve("github")          # by server name
+      route = router.resolve_by_tool("git_push") # by tool name (after discovery)
+    """
+
+    def __init__(self, default_upstream: str = "http://localhost:9000"):
+        self.default_upstream = default_upstream
+        self.routes: dict[str, ServerRoute] = {}
+        self.tool_to_server: dict[str, str] = {}
+        self.governance_config: dict = {}
+        self._loaded = False
+
+    def load_config(self, config_path: str | Path) -> None:
+        """Load routing configuration from JSON file."""
+        path = Path(config_path)
+        if not path.exists():
+            logger.warning("Routing config not found: %s, using default upstream", path)
+            return
+
+        with open(path) as f:
+            config = json.load(f)
+
+        self.default_upstream = config.get("default_upstream", self.default_upstream)
+        self.governance_config = config.get("governance", {})
+
+        for name, route_def in config.get("routes", {}).items():
+            self.routes[name] = ServerRoute(
+                name=name,
+                upstream_url=route_def.get("upstream_url", ""),
+                server_type=route_def.get("type", "sse"),
+                proxy_mode=route_def.get("proxy_mode", "transparent"),
+                headers=route_def.get("headers", {}),
+            )
+
+        self._loaded = True
+        logger.info("Loaded %d upstream routes from %s", len(self.routes), path)
+
+    def resolve(self, server_name: str) -> ServerRoute | None:
+        """Resolve a server route by name."""
+        route = self.routes.get(server_name)
+        if route:
+            route.request_count += 1
+        return route
+
+    def resolve_by_tool(self, tool_name: str) -> ServerRoute | None:
+        """Resolve which server provides a given tool."""
+        server_name = self.tool_to_server.get(tool_name)
+        if server_name:
+            return self.resolve(server_name)
+        return None
+
+    def register_tool_mapping(self, server_name: str, tool_names: list[str]) -> None:
+        """After tool discovery, map tool names to their server."""
+        for tool in tool_names:
+            self.tool_to_server[tool] = server_name
+        route = self.routes.get(server_name)
+        if route:
+            route.tool_names = tool_names
+        logger.info("Registered %d tools for server '%s'", len(tool_names), server_name)
+
+    def get_upstream_url(self, server_name: str | None = None) -> str:
+        """Get the upstream URL for a given server, or default."""
+        if server_name:
+            route = self.resolve(server_name)
+            if route and route.upstream_url:
+                return route.upstream_url
+        return self.default_upstream
+
+    def get_upstream_headers(self, server_name: str | None = None) -> dict:
+        """Get any extra headers for the upstream server."""
+        if server_name:
+            route = self.resolve(server_name)
+            if route:
+                return route.headers
+        return {}
+
+    def record_block(self, server_name: str) -> None:
+        """Record that a request to this server was blocked."""
+        route = self.routes.get(server_name)
+        if route:
+            route.block_count += 1
+
+    def get_stats(self) -> dict:
+        """Return routing statistics."""
+        return {
+            "total_routes": len(self.routes),
+            "loaded": self._loaded,
+            "default_upstream": self.default_upstream,
+            "routes": {
+                name: {
+                    "type": r.server_type,
+                    "upstream": r.upstream_url or "(stdio)",
+                    "requests": r.request_count,
+                    "blocks": r.block_count,
+                    "tools": len(r.tool_names),
+                    "healthy": r.healthy,
+                }
+                for name, r in self.routes.items()
+            },
+            "tool_mappings": len(self.tool_to_server),
+        }
+
+    @property
+    def is_multi_upstream(self) -> bool:
+        """Whether multi-upstream mode is active."""
+        return self._loaded and len(self.routes) > 0

admina/proxy/state.py

@@ -0,0 +1,97 @@
+# 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.
+
+"""Proxy runtime state — holds connections, engines, and metrics."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+import redis.asyncio as aioredis
+from minio import Minio
+
+from admina.domains.compliance.eu_ai_act import EUAIActCompliance
+from admina.domains.compliance.forensic import ForensicBlackBox
+from admina.domains.compliance.gdpr import ProcessingActivitiesRegistry
+from admina.domains.compliance.nis2 import NIS2Compliance
+from admina.domains.compliance.otel import OTELGovernanceExporter
+from admina.plugins.registry import PluginRegistry
+from admina.proxy.multi_upstream import MultiUpstreamRouter
+
+
+@dataclass
+class ProxyState:
+    """Mutable runtime state for the proxy.
+
+    Created once at startup, passed to handlers via app.state.
+    """
+
+    # Connections
+    redis: aioredis.Redis | None = None
+    minio: Minio | None = None
+    clickhouse: Any = None
+    http_client: httpx.AsyncClient | None = None
+
+    # Governance engines (set by engine_bridge)
+    firewall: Any = None
+    pii_redactor: Any = None
+    loop_breaker: Any = None
+
+    # Subsystems
+    forensic_box: ForensicBlackBox | None = None
+    compliance: EUAIActCompliance = field(default_factory=EUAIActCompliance)
+    nis2: NIS2Compliance = field(default_factory=NIS2Compliance)
+    gdpr: ProcessingActivitiesRegistry = field(default_factory=ProcessingActivitiesRegistry)
+    router: MultiUpstreamRouter | None = None
+    registry: PluginRegistry = field(default_factory=PluginRegistry)
+
+    # Plugins
+    governance_guards: list = field(default_factory=list)
+    alert_channels: list = field(default_factory=list)
+    auth_providers: list = field(default_factory=list)
+
+    # OTEL
+    otel_exporter: OTELGovernanceExporter | None = None
+
+    # Metrics
+    metrics: dict[str, Any] = field(
+        default_factory=lambda: {
+            "requests_total": 0,
+            "requests_blocked": 0,
+            "requests_allowed": 0,
+            "requests_redacted": 0,
+            "avg_latency_ms": 0.0,
+            "started_at": datetime.now(UTC).isoformat(),
+        }
+    )
+    _metrics_lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def inc_metric(self, key: str, value: int = 1) -> None:
+        with self._metrics_lock:
+            self.metrics[key] += value
+
+    def update_avg_latency(self, latency_ms: float) -> None:
+        with self._metrics_lock:
+            n = self.metrics["requests_total"]
+            if n <= 1:
+                self.metrics["avg_latency_ms"] = latency_ms
+            else:
+                self.metrics["avg_latency_ms"] = round(
+                    (self.metrics["avg_latency_ms"] * (n - 1) + latency_ms) / n,
+                    2,
+                )

admina/sdk/__init__.py

@@ -0,0 +1,34 @@
+# 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 SDK — governed AI primitives.
+
+Usage::
+
+    from admina.sdk import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
+"""
+
+from __future__ import annotations
+
+from admina.sdk.compliance_kit import ComplianceKit
+from admina.sdk.governed_agent import GovernedAgent
+from admina.sdk.governed_data import GovernedData
+from admina.sdk.governed_model import GovernedModel
+
+__all__ = [
+    "GovernedModel",
+    "GovernedData",
+    "GovernedAgent",
+    "ComplianceKit",
+]

admina/sdk/_compat.py

@@ -0,0 +1,43 @@
+# 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.
+
+"""Async-to-sync bridge that works both inside and outside running loops."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine synchronously.
+
+    Works correctly whether or not an event loop is already running.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop — safe to use asyncio.run()
+        return asyncio.run(coro)
+    else:
+        # Inside a running loop (Jupyter, FastAPI, etc.)
+        # Create a new thread to avoid deadlock
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(asyncio.run, coro)
+            return future.result()

admina/sdk/compliance_kit.py

@@ -0,0 +1,359 @@
+# 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 — ComplianceKit SDK primitive.
+
+Wraps the existing EU AI Act compliance engine and provides a unified
+interface for risk classification, gap analysis, and report generation
+across compliance frameworks.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from admina.core.event_bus import EventType, GovernanceEvent, bus
+from admina.domains.compliance.eu_ai_act import EUAIActCompliance
+from admina.sdk._compat import run_sync
+
+__all__ = ["ComplianceKit"]
+
+
+@dataclass
+class RiskClassification:
+    """Result of a risk classification.
+
+    Attributes:
+        risk_category: The risk category (unacceptable, high, limited, minimal).
+        level: Numeric risk level (1-4).
+        description: Human-readable description.
+        action: Required action for this risk level.
+        framework: The compliance framework used.
+    """
+
+    risk_category: str
+    level: int = 1
+    description: str = ""
+    action: str = ""
+    framework: str = "eu_ai_act"
+
+
+@dataclass
+class GapReport:
+    """Result of a gap analysis.
+
+    Attributes:
+        applicable: Whether gap analysis applies to this risk level.
+        compliance_score: Percentage of checks passed (0-100).
+        total_checks: Total number of checks evaluated.
+        passed_checks: Number of checks passed.
+        gaps: List of unmet requirements.
+        status: COMPLIANT or GAPS_FOUND.
+        framework: The compliance framework used.
+        message: Optional message (e.g. for non-applicable cases).
+    """
+
+    applicable: bool = False
+    compliance_score: float = 0.0
+    total_checks: int = 0
+    passed_checks: int = 0
+    gaps: list[dict[str, Any]] = field(default_factory=list)
+    status: str = "GAPS_FOUND"
+    framework: str = "eu_ai_act"
+    message: str = ""
+
+
+@dataclass
+class Report:
+    """A generated compliance report.
+
+    Attributes:
+        title: Report title.
+        generated_at: ISO timestamp of generation.
+        framework: The compliance framework.
+        classification: Risk classification details.
+        gap_analysis: Gap analysis details.
+        recommendations: List of recommended actions.
+        content: Full report content dict.
+    """
+
+    title: str = ""
+    generated_at: str = ""
+    framework: str = "eu_ai_act"
+    classification: dict[str, Any] = field(default_factory=dict)
+    gap_analysis: dict[str, Any] = field(default_factory=dict)
+    recommendations: list[str] = field(default_factory=list)
+    content: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        """Serialize the report to JSON string.
+
+        Returns:
+            JSON string of the report content.
+        """
+        return json.dumps(self.content, indent=2, default=str)
+
+
+class ComplianceKit:
+    """SDK primitive for compliance checking and reporting.
+
+    Provides risk classification, gap analysis, and report generation
+    across compliance frameworks. Currently supports EU AI Act with
+    extensibility for additional frameworks via plugin templates.
+
+    Args:
+        frameworks: List of framework names to activate.
+            Defaults to ["eu_ai_act"].
+        audit: Whether to emit governance events.
+    """
+
+    def __init__(
+        self,
+        frameworks: list[str] | None = None,
+        audit: bool = True,
+    ) -> None:
+        """Initialize ComplianceKit.
+
+        Args:
+            frameworks: Framework names to activate. Defaults to ["eu_ai_act"].
+            audit: If True, emit events to the event bus.
+        """
+        self._frameworks = frameworks or ["eu_ai_act"]
+        self._audit = audit
+        self._engines: dict[str, Any] = {}
+        self._init_engines()
+
+    def _init_engines(self) -> None:
+        """Initialize compliance engines for configured frameworks."""
+        for fw in self._frameworks:
+            if fw == "eu_ai_act":
+                self._engines[fw] = EUAIActCompliance()
+
+    def _get_engine(self, framework: str) -> Any:
+        """Get the compliance engine for a framework.
+
+        Args:
+            framework: Framework name.
+
+        Returns:
+            The compliance engine instance.
+
+        Raises:
+            ValueError: If the framework is not supported.
+        """
+        engine = self._engines.get(framework)
+        if engine is None:
+            raise ValueError(
+                f"Framework '{framework}' is not supported. Available: {list(self._engines.keys())}"
+            )
+        return engine
+
+    def classify_risk(
+        self,
+        description: str,
+        use_case: str,
+        data_types: list[str] | None = None,
+        framework: str = "eu_ai_act",
+    ) -> RiskClassification:
+        """Classify an AI system's risk level.
+
+        Args:
+            description: Description of the AI system.
+            use_case: The use case or application domain.
+            data_types: Types of data processed (e.g. ["health", "financial"]).
+            framework: Compliance framework to use.
+
+        Returns:
+            RiskClassification with category, level, and required action.
+        """
+        engine = self._get_engine(framework)
+        result = engine.classify_risk(
+            description,
+            use_case,
+            data_types or [],
+        )
+
+        classification = RiskClassification(
+            risk_category=result["risk_category"],
+            level=result.get("level", 1),
+            description=result.get("description", ""),
+            action=result.get("action", ""),
+            framework=framework,
+        )
+
+        if self._audit:
+            _emit_sync(
+                GovernanceEvent(
+                    event_type=EventType.COMPLIANCE_CHECK,
+                    domain="compliance",
+                    action="ALLOW",
+                    metadata={
+                        "operation": "classify_risk",
+                        "framework": framework,
+                        "risk_category": classification.risk_category,
+                        "level": classification.level,
+                    },
+                )
+            )
+
+        return classification
+
+    def gap_analysis(
+        self,
+        framework: str = "eu_ai_act",
+        risk_category: str = "high",
+        current_compliance: dict[str, list[bool] | bool] | None = None,
+    ) -> GapReport:
+        """Perform a compliance gap analysis.
+
+        Args:
+            framework: Compliance framework to evaluate.
+            risk_category: The risk category to analyze gaps for.
+            current_compliance: Dict mapping requirement keys to either
+                a list of booleans (one per check) or a single boolean
+                (treated as a single check that is fully met or unmet).
+
+        Returns:
+            GapReport with score, gaps, and status.
+
+        Raises:
+            ValueError: If a value is not a bool or list of bools.
+        """
+        engine = self._get_engine(framework)
+        normalised: dict[str, list[bool]] = {}
+        for key, value in (current_compliance or {}).items():
+            if isinstance(value, bool):
+                normalised[key] = [value]
+            elif isinstance(value, list) and all(isinstance(v, bool) for v in value):
+                normalised[key] = value
+            else:
+                raise ValueError(
+                    f"current_compliance[{key!r}] must be bool or list[bool], "
+                    f"got {type(value).__name__}"
+                )
+        result = engine.gap_analysis(risk_category, normalised)
+
+        report = GapReport(
+            applicable=result.get("applicable", False),
+            compliance_score=result.get("compliance_score", 0.0),
+            total_checks=result.get("total_checks", 0),
+            passed_checks=result.get("passed_checks", 0),
+            gaps=result.get("gaps", []),
+            status=result.get("status", "GAPS_FOUND"),
+            framework=framework,
+            message=result.get("message", ""),
+        )
+
+        if self._audit:
+            _emit_sync(
+                GovernanceEvent(
+                    event_type=EventType.COMPLIANCE_CHECK,
+                    domain="compliance",
+                    metadata={
+                        "operation": "gap_analysis",
+                        "framework": framework,
+                        "applicable": report.applicable,
+                        "compliance_score": report.compliance_score,
+                        "gap_count": len(report.gaps),
+                    },
+                )
+            )
+
+        return report
+
+    def generate_report(
+        self,
+        system_name: str,
+        description: str,
+        use_case: str,
+        data_types: list[str] | None = None,
+        current_compliance: dict[str, list[bool]] | None = None,
+        framework: str = "eu_ai_act",
+    ) -> Report:
+        """Generate a full compliance report.
+
+        Runs risk classification and gap analysis, then produces a
+        structured report with recommendations.
+
+        Args:
+            system_name: Name of the AI system.
+            description: Description of the AI system.
+            use_case: The use case or application domain.
+            data_types: Types of data processed.
+            current_compliance: Current compliance state for gap analysis.
+            framework: Compliance framework to use.
+
+        Returns:
+            Report with classification, gaps, and recommendations.
+        """
+        engine = self._get_engine(framework)
+
+        classification = engine.classify_risk(
+            description,
+            use_case,
+            data_types or [],
+        )
+        gap_result = engine.gap_analysis(
+            classification["risk_category"],
+            current_compliance or {},
+        )
+        report_data = engine.generate_report(
+            system_name,
+            classification,
+            gap_result,
+        )
+
+        report = Report(
+            title=report_data.get("report_title", ""),
+            generated_at=report_data.get("generated_at", ""),
+            framework=framework,
+            classification=classification,
+            gap_analysis=gap_result,
+            recommendations=report_data.get("recommendations", []),
+            content=report_data,
+        )
+
+        if self._audit:
+            _emit_sync(
+                GovernanceEvent(
+                    event_type=EventType.COMPLIANCE_CHECK,
+                    domain="compliance",
+                    metadata={
+                        "operation": "generate_report",
+                        "framework": framework,
+                        "system_name": system_name,
+                        "risk_category": classification["risk_category"],
+                    },
+                )
+            )
+
+        return report
+
+    @property
+    def supported_frameworks(self) -> list[str]:
+        """Return list of supported framework names."""
+        return list(self._engines.keys())
+
+
+def _emit_sync(event: GovernanceEvent) -> None:
+    """Emit an event synchronously.
+
+    Uses an event loop if available, otherwise creates one.
+
+    Args:
+        event: The governance event to emit.
+    """
+    run_sync(bus.emit(event))