socratic-knowledge 0.1.0__py3-none-any.whl

socratic_knowledge/__init__.py

@@ -0,0 +1,26 @@
+"""
+Socratic Knowledge - Enterprise knowledge management system.
+
+Provides multi-tenant knowledge management with access control, versioning,
+and RAG integration.
+"""
+
+from .core.collection import Collection
+from .core.knowledge_item import KnowledgeItem
+from .core.tenant import Tenant
+from .core.user import User
+from .core.version import Version
+from .manager import KnowledgeManager
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core models
+    "KnowledgeItem",
+    "Collection",
+    "Tenant",
+    "User",
+    "Version",
+    # Manager
+    "KnowledgeManager",
+]

socratic_knowledge/access/__init__.py

@@ -0,0 +1,9 @@
+"""Access control module."""
+
+from .rbac import ROLE_PERMISSIONS, Permission, Role
+
+__all__ = [
+    "Permission",
+    "Role",
+    "ROLE_PERMISSIONS",
+]

socratic_knowledge/access/permissions.py

@@ -0,0 +1,234 @@
+"""Permission checking and enforcement."""
+
+from typing import Dict, List, Optional, Set
+
+from ..core.collection import Collection
+from ..core.knowledge_item import KnowledgeItem
+from .rbac import Permission, Role, ROLE_PERMISSIONS
+
+
+class AccessControl:
+    """
+    Role-based access control (RBAC) engine.
+
+    Checks if user has permission to perform action on resource.
+    """
+
+    @staticmethod
+    def check_permission(
+        user_id: str,
+        item: KnowledgeItem,
+        permission: Permission,
+    ) -> bool:
+        """
+        Check if user has permission on item.
+
+        Args:
+            user_id: User ID
+            item: Knowledge item
+            permission: Permission to check
+
+        Returns:
+            bool: True if user has permission
+        """
+        # Owner always has access
+        if item.owner_id == user_id:
+            return True
+
+        # Check role-based permissions
+        if not item.permissions:
+            return False
+
+        for role_str, user_ids in item.permissions.items():
+            if user_id in user_ids:
+                try:
+                    role = Role[role_str.upper()]
+                except KeyError:
+                    continue
+
+                role_permissions = ROLE_PERMISSIONS.get(role, set())
+                if permission in role_permissions:
+                    return True
+
+        return False
+
+    @staticmethod
+    def check_collection_permission(
+        user_id: str,
+        collection: Collection,
+        permission: Permission,
+        storage: Optional[object] = None,
+    ) -> bool:
+        """
+        Check permission with inheritance from parent collections.
+
+        Args:
+            user_id: User ID
+            collection: Collection
+            permission: Permission to check
+            storage: Storage instance for fetching parents
+
+        Returns:
+            bool: True if user has permission
+        """
+        # Direct permission
+        if AccessControl._has_collection_permission(
+            user_id,
+            collection,
+            permission,
+        ):
+            return True
+
+        # Check parent hierarchy if inheritance enabled
+        if collection.inherit_permissions and collection.parent_id and storage:
+            parent = storage.get_collection(collection.parent_id)
+            if parent:
+                return AccessControl.check_collection_permission(
+                    user_id,
+                    parent,
+                    permission,
+                    storage,
+                )
+
+        return False
+
+    @staticmethod
+    def _has_collection_permission(
+        user_id: str,
+        collection: Collection,
+        permission: Permission,
+    ) -> bool:
+        """
+        Check direct permission on collection.
+
+        Args:
+            user_id: User ID
+            collection: Collection
+            permission: Permission to check
+
+        Returns:
+            bool: True if user has permission
+        """
+        # Owner always has access
+        if collection.owner_id == user_id:
+            return True
+
+        if not collection.permissions:
+            return False
+
+        for role_str, user_ids in collection.permissions.items():
+            if user_id in user_ids:
+                try:
+                    role = Role[role_str.upper()]
+                except KeyError:
+                    continue
+
+                role_permissions = ROLE_PERMISSIONS.get(role, set())
+                if permission in role_permissions:
+                    return True
+
+        return False
+
+    @staticmethod
+    def grant_permission(
+        item: KnowledgeItem,
+        user_id: str,
+        role: Role,
+    ) -> None:
+        """
+        Grant permission to user.
+
+        Args:
+            item: Knowledge item
+            user_id: User to grant permission to
+            role: Role to grant
+        """
+        if item.permissions is None:
+            item.permissions = {}
+
+        role_str = role.value
+        if role_str not in item.permissions:
+            item.permissions[role_str] = []
+
+        if user_id not in item.permissions[role_str]:
+            item.permissions[role_str].append(user_id)
+
+    @staticmethod
+    def revoke_permission(
+        item: KnowledgeItem,
+        user_id: str,
+        role: Optional[Role] = None,
+    ) -> None:
+        """
+        Revoke permission from user.
+
+        Args:
+            item: Knowledge item
+            user_id: User to revoke permission from
+            role: Specific role to revoke, or None to revoke all
+        """
+        if not item.permissions:
+            return
+
+        if role:
+            role_str = role.value
+            if role_str in item.permissions:
+                if user_id in item.permissions[role_str]:
+                    item.permissions[role_str].remove(user_id)
+        else:
+            # Revoke all roles for user
+            for role_str in item.permissions:
+                if user_id in item.permissions[role_str]:
+                    item.permissions[role_str].remove(user_id)
+
+    @staticmethod
+    def grant_collection_permission(
+        collection: Collection,
+        user_id: str,
+        role: Role,
+    ) -> None:
+        """
+        Grant permission on collection.
+
+        Args:
+            collection: Collection
+            user_id: User to grant permission to
+            role: Role to grant
+        """
+        if collection.permissions is None:
+            collection.permissions = {}
+
+        role_str = role.value
+        if role_str not in collection.permissions:
+            collection.permissions[role_str] = []
+
+        if user_id not in collection.permissions[role_str]:
+            collection.permissions[role_str].append(user_id)
+
+    @staticmethod
+    def revoke_collection_permission(
+        collection: Collection,
+        user_id: str,
+        role: Optional[Role] = None,
+    ) -> None:
+        """
+        Revoke permission on collection.
+
+        Args:
+            collection: Collection
+            user_id: User to revoke permission from
+            role: Specific role to revoke, or None to revoke all
+        """
+        if not collection.permissions:
+            return
+
+        if role:
+            role_str = role.value
+            if role_str in collection.permissions:
+                if user_id in collection.permissions[role_str]:
+                    collection.permissions[role_str].remove(user_id)
+        else:
+            # Revoke all roles for user
+            for role_str in collection.permissions:
+                if user_id in collection.permissions[role_str]:
+                    collection.permissions[role_str].remove(user_id)

socratic_knowledge/access/rbac.py

@@ -0,0 +1,37 @@
+"""Role-Based Access Control (RBAC) implementation."""
+
+from enum import Enum
+from typing import Set
+
+
+class Permission(Enum):
+    """Fine-grained permissions."""
+
+    READ = "read"
+    WRITE = "write"
+    DELETE = "delete"
+    SHARE = "share"
+    ADMIN = "admin"
+
+
+class Role(Enum):
+    """Predefined roles with permission sets."""
+
+    VIEWER = "viewer"
+    EDITOR = "editor"
+    ADMIN = "admin"
+    OWNER = "owner"
+
+
+ROLE_PERMISSIONS: dict[Role, Set[Permission]] = {
+    Role.VIEWER: {Permission.READ},
+    Role.EDITOR: {Permission.READ, Permission.WRITE},
+    Role.ADMIN: {Permission.READ, Permission.WRITE, Permission.DELETE, Permission.SHARE},
+    Role.OWNER: {
+        Permission.READ,
+        Permission.WRITE,
+        Permission.DELETE,
+        Permission.SHARE,
+        Permission.ADMIN,
+    },
+}

socratic_knowledge/audit/__init__.py

@@ -0,0 +1,10 @@
+"""Audit logging and compliance module."""
+
+from .events import AuditEvent, AuditEventType
+from .logger import AuditLogger
+
+__all__ = [
+    "AuditEvent",
+    "AuditEventType",
+    "AuditLogger",
+]

socratic_knowledge/audit/events.py

@@ -0,0 +1,91 @@
+"""Audit event types and models."""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class AuditEventType(Enum):
+    """Types of audit events."""
+
+    # Item operations
+    ITEM_CREATED = "item_created"
+    ITEM_UPDATED = "item_updated"
+    ITEM_DELETED = "item_deleted"
+    ITEM_VIEWED = "item_viewed"
+
+    # Collection operations
+    COLLECTION_CREATED = "collection_created"
+    COLLECTION_UPDATED = "collection_updated"
+    COLLECTION_DELETED = "collection_deleted"
+
+    # Tenant operations
+    TENANT_CREATED = "tenant_created"
+    TENANT_UPDATED = "tenant_updated"
+
+    # Access control
+    PERMISSION_GRANTED = "permission_granted"
+    PERMISSION_REVOKED = "permission_revoked"
+
+    # Version operations
+    VERSION_CREATED = "version_created"
+    ITEM_ROLLED_BACK = "item_rolled_back"
+
+    # Search operations
+    SEARCH_EXECUTED = "search_executed"
+
+    # Conflict operations
+    CONFLICT_DETECTED = "conflict_detected"
+    CONFLICT_RESOLVED = "conflict_resolved"
+
+
+@dataclass
+class AuditEvent:
+    """Represents a single audit event."""
+
+    event_id: str
+    event_type: AuditEventType
+    tenant_id: str
+    user_id: str
+    resource_type: str  # "item", "collection", "tenant", etc.
+    resource_id: str
+    action: str  # "create", "update", "delete", etc.
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    changes: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "event_id": self.event_id,
+            "event_type": self.event_type.value,
+            "tenant_id": self.tenant_id,
+            "user_id": self.user_id,
+            "resource_type": self.resource_type,
+            "resource_id": self.resource_id,
+            "action": self.action,
+            "timestamp": self.timestamp.isoformat(),
+            "changes": self.changes,
+            "metadata": self.metadata,
+            "ip_address": self.ip_address,
+            "user_agent": self.user_agent,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AuditEvent":
+        """Deserialize from dictionary."""
+        event_type = data.get("event_type")
+        if isinstance(event_type, str):
+            data = {
+                **data,
+                "event_type": AuditEventType(event_type),
+            }
+
+        timestamp = data.get("timestamp")
+        if isinstance(timestamp, str):
+            data = {**data, "timestamp": datetime.fromisoformat(timestamp)}
+
+        return cls(**data)

socratic_knowledge/audit/logger.py

@@ -0,0 +1,216 @@
+"""Audit logging for knowledge management operations."""
+
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from .events import AuditEvent, AuditEventType
+
+
+class AuditLogger:
+    """
+    Audit logging system for tracking all operations.
+
+    Maintains a complete audit trail for compliance and debugging.
+    """
+
+    def __init__(self):
+        """Initialize audit logger."""
+        self._events: List[AuditEvent] = []
+
+    def log_event(
+        self,
+        event_type: AuditEventType,
+        tenant_id: str,
+        user_id: str,
+        resource_type: str,
+        resource_id: str,
+        action: str,
+        changes: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        ip_address: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> AuditEvent:
+        """
+        Log an audit event.
+
+        Args:
+            event_type: Type of event
+            tenant_id: Tenant ID
+            user_id: User performing action
+            resource_type: Type of resource (item, collection, etc.)
+            resource_id: ID of resource
+            action: Action performed (create, update, delete, etc.)
+            changes: Dictionary of changes made
+            metadata: Optional metadata
+            ip_address: Optional IP address of user
+            user_agent: Optional user agent string
+
+        Returns:
+            AuditEvent: Logged event
+        """
+        event = AuditEvent(
+            event_id=str(uuid4()),
+            event_type=event_type,
+            tenant_id=tenant_id,
+            user_id=user_id,
+            resource_type=resource_type,
+            resource_id=resource_id,
+            action=action,
+            changes=changes or {},
+            metadata=metadata or {},
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+        self._events.append(event)
+        return event
+
+    def get_events(
+        self,
+        tenant_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        resource_id: Optional[str] = None,
+        event_type: Optional[AuditEventType] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[AuditEvent]:
+        """
+        Query audit events.
+
+        Args:
+            tenant_id: Filter by tenant
+            user_id: Filter by user
+            resource_id: Filter by resource
+            event_type: Filter by event type
+            limit: Maximum events to return
+            offset: Number of events to skip
+
+        Returns:
+            List[AuditEvent]: Matching events
+        """
+        results = self._events
+
+        if tenant_id:
+            results = [e for e in results if e.tenant_id == tenant_id]
+
+        if user_id:
+            results = [e for e in results if e.user_id == user_id]
+
+        if resource_id:
+            results = [e for e in results if e.resource_id == resource_id]
+
+        if event_type:
+            results = [e for e in results if e.event_type == event_type]
+
+        # Return in reverse chronological order
+        results = list(reversed(results))
+
+        return results[offset : offset + limit]
+
+    def get_user_activity(
+        self,
+        tenant_id: str,
+        user_id: str,
+        limit: int = 50,
+    ) -> List[AuditEvent]:
+        """
+        Get activity for specific user.
+
+        Args:
+            tenant_id: Tenant ID
+            user_id: User ID
+            limit: Maximum events to return
+
+        Returns:
+            List[AuditEvent]: User's recent actions
+        """
+        return self.get_events(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            limit=limit,
+        )
+
+    def get_resource_history(
+        self,
+        resource_id: str,
+        limit: int = 50,
+    ) -> List[AuditEvent]:
+        """
+        Get change history for specific resource.
+
+        Args:
+            resource_id: Resource ID
+            limit: Maximum events to return
+
+        Returns:
+            List[AuditEvent]: Resource history
+        """
+        return self.get_events(
+            resource_id=resource_id,
+            limit=limit,
+        )
+
+    def get_tenant_audit_log(
+        self,
+        tenant_id: str,
+        limit: int = 100,
+    ) -> List[AuditEvent]:
+        """
+        Get complete audit log for tenant.
+
+        Args:
+            tenant_id: Tenant ID
+            limit: Maximum events to return
+
+        Returns:
+            List[AuditEvent]: Tenant audit trail
+        """
+        return self.get_events(
+            tenant_id=tenant_id,
+            limit=limit,
+        )
+
+    def clear_events(self, tenant_id: Optional[str] = None) -> int:
+        """
+        Clear audit events.
+
+        Args:
+            tenant_id: If specified, only clear events for this tenant
+
+        Returns:
+            int: Number of events cleared
+        """
+        if not tenant_id:
+            count = len(self._events)
+            self._events = []
+            return count
+
+        original_count = len(self._events)
+        self._events = [e for e in self._events if e.tenant_id != tenant_id]
+        return original_count - len(self._events)
+
+    def count_events(
+        self,
+        tenant_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> int:
+        """
+        Count audit events.
+
+        Args:
+            tenant_id: Optional tenant filter
+            user_id: Optional user filter
+
+        Returns:
+            int: Number of matching events
+        """
+        count = len(self._events)
+
+        if tenant_id:
+            count = len([e for e in self._events if e.tenant_id == tenant_id])
+
+        if user_id:
+            count = len(
+                [e for e in self._events if e.tenant_id == tenant_id and e.user_id == user_id]
+            )
+
+        return count

socratic_knowledge/collaboration/__init__.py

@@ -0,0 +1,13 @@
+"""Collaboration and concurrent edit management module."""
+
+from .conflict import Conflict, ConflictDetector, ConflictResolutionStrategy, ConflictType
+from .locks import LockToken, OptimisticLockManager
+
+__all__ = [
+    "LockToken",
+    "OptimisticLockManager",
+    "Conflict",
+    "ConflictType",
+    "ConflictDetector",
+    "ConflictResolutionStrategy",
+]