mesa-core 1.0.0__py3-none-any.whl

mesa_core/__init__.py

@@ -0,0 +1,76 @@
+"""mesa-core: reference implementation of the MESA specification."""
+
+from mesa_core.conflict import ConflictResolver
+from mesa_core.enforcer import ConfirmationManager, EnforcementResult, MesaEnforcer
+from mesa_core.exceptions import (
+    InvalidCursorError,
+    MesaEnforcementError,
+    MesaError,
+    MesaValidationError,
+)
+from mesa_core.inheritance import InheritanceResolver, ProfileExplanation
+from mesa_core.integration_import import import_from_integration
+from mesa_core.migration import migrate_profile
+from mesa_core.privacy import AccessDecision, CallerContext, PrivacyEnforcer
+from mesa_core.profile import (
+    DOMAIN_SAFETY_BASELINE,
+    HELPER_DOMAINS,
+    ControlMode,
+    MetadataOrigin,
+    OperationalBoundaries,
+    PrivacyClassification,
+    PrivacyLevel,
+    ProfileMetadata,
+    SemanticProfile,
+    TriggersAutomations,
+)
+from mesa_core.store import DeploymentDefaults, ProfileQueryResult, ProfileStore, QueryRow
+from mesa_core.temporal import TemporalEvaluator, TemporalResult
+from mesa_core.trigger_validator import (
+    TriggerValidator,
+    ValidationIssue,
+    entities_by_role,
+)
+from mesa_core.validation import ValidationReport, validate_document, validate_or_raise
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "DOMAIN_SAFETY_BASELINE",
+    "HELPER_DOMAINS",
+    "AccessDecision",
+    "CallerContext",
+    "ConfirmationManager",
+    "ConflictResolver",
+    "ControlMode",
+    "DeploymentDefaults",
+    "EnforcementResult",
+    "InheritanceResolver",
+    "InvalidCursorError",
+    "MesaEnforcementError",
+    "MesaEnforcer",
+    "MesaError",
+    "MesaValidationError",
+    "MetadataOrigin",
+    "OperationalBoundaries",
+    "PrivacyClassification",
+    "PrivacyEnforcer",
+    "PrivacyLevel",
+    "ProfileExplanation",
+    "ProfileMetadata",
+    "ProfileQueryResult",
+    "ProfileStore",
+    "QueryRow",
+    "SemanticProfile",
+    "TemporalEvaluator",
+    "TemporalResult",
+    "TriggerValidator",
+    "TriggersAutomations",
+    "ValidationIssue",
+    "ValidationReport",
+    "entities_by_role",
+    "import_from_integration",
+    "migrate_profile",
+    "validate_document",
+    "validate_or_raise",
+]

mesa_core/backends/__init__.py

@@ -0,0 +1,29 @@
+"""Storage backends for ProfileStore (Module Proposal 4.3)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class StorageBackend(ABC):
+    """Abstract storage backend. Host servers may implement their own."""
+
+    @abstractmethod
+    def read(self, key: str) -> dict[str, Any] | None: ...
+
+    @abstractmethod
+    def write(self, key: str, data: dict[str, Any]) -> None: ...
+
+    @abstractmethod
+    def delete(self, key: str) -> None: ...
+
+    @abstractmethod
+    def list_keys(self, prefix: str | None = None) -> list[str]: ...
+
+
+from mesa_core.backends.jsonfile import JsonFileBackend  # noqa: E402
+from mesa_core.backends.memory import MemoryBackend  # noqa: E402
+from mesa_core.backends.sqlite import SqliteBackend  # noqa: E402
+
+__all__ = ["JsonFileBackend", "MemoryBackend", "SqliteBackend", "StorageBackend"]

mesa_core/backends/jsonfile.py

@@ -0,0 +1,43 @@
+"""JSON file storage backend: one file per profile, keyed by URL-quoted key.
+
+Quoting (rather than lossy character replacement) keeps the filename-to-key
+mapping reversible, so ``list_keys`` can reconstruct keys exactly.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote, unquote
+
+from mesa_core import backends
+
+
+class JsonFileBackend(backends.StorageBackend):
+    def __init__(self, base_path: str | Path, create_if_missing: bool = True) -> None:
+        self.base_path = Path(base_path)
+        if create_if_missing:
+            self.base_path.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, key: str) -> Path:
+        return self.base_path / f"{quote(key, safe='')}.json"
+
+    def read(self, key: str) -> dict[str, Any] | None:
+        path = self._path(key)
+        if not path.exists():
+            return None
+        data: dict[str, Any] = json.loads(path.read_text())
+        return data
+
+    def write(self, key: str, data: dict[str, Any]) -> None:
+        self._path(key).write_text(json.dumps(data, indent=2) + "\n")
+
+    def delete(self, key: str) -> None:
+        self._path(key).unlink(missing_ok=True)
+
+    def list_keys(self, prefix: str | None = None) -> list[str]:
+        keys = sorted(unquote(p.stem) for p in self.base_path.glob("*.json"))
+        if prefix is not None:
+            keys = [k for k in keys if k.startswith(prefix)]
+        return keys

mesa_core/backends/memory.py

@@ -0,0 +1,29 @@
+"""In-memory storage backend. Not persistent; for testing and development."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from mesa_core import backends
+
+
+class MemoryBackend(backends.StorageBackend):
+    def __init__(self, initial_data: dict[str, dict[str, Any]] | None = None) -> None:
+        self._data: dict[str, dict[str, Any]] = copy.deepcopy(initial_data or {})
+
+    def read(self, key: str) -> dict[str, Any] | None:
+        value = self._data.get(key)
+        return copy.deepcopy(value) if value is not None else None
+
+    def write(self, key: str, data: dict[str, Any]) -> None:
+        self._data[key] = copy.deepcopy(data)
+
+    def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+    def list_keys(self, prefix: str | None = None) -> list[str]:
+        keys = sorted(self._data)
+        if prefix is not None:
+            keys = [k for k in keys if k.startswith(prefix)]
+        return keys

mesa_core/backends/sqlite.py

@@ -0,0 +1,57 @@
+"""SQLite storage backend using the standard library.
+
+Suitable for large deployments. Async access goes through the ProfileStore's
+``a``-prefixed methods, which offload to a thread.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from mesa_core import backends
+
+
+class SqliteBackend(backends.StorageBackend):
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = str(db_path)
+        with self._connect() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS profiles (key TEXT PRIMARY KEY, data TEXT NOT NULL)"
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.db_path)
+
+    def read(self, key: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute("SELECT data FROM profiles WHERE key = ?", (key,)).fetchone()
+        if row is None:
+            return None
+        data: dict[str, Any] = json.loads(row[0])
+        return data
+
+    def write(self, key: str, data: dict[str, Any]) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO profiles (key, data) VALUES (?, ?) "
+                "ON CONFLICT(key) DO UPDATE SET data = excluded.data",
+                (key, json.dumps(data)),
+            )
+
+    def delete(self, key: str) -> None:
+        with self._connect() as conn:
+            conn.execute("DELETE FROM profiles WHERE key = ?", (key,))
+
+    def list_keys(self, prefix: str | None = None) -> list[str]:
+        query = "SELECT key FROM profiles"
+        params: tuple[Any, ...] = ()
+        if prefix is not None:
+            query += " WHERE key LIKE ?"
+            params = (prefix.replace("%", r"\%").replace("_", r"\_") + "%",)
+            query += r" ESCAPE '\'"
+        query += " ORDER BY key"
+        with self._connect() as conn:
+            return [row[0] for row in conn.execute(query, params)]