Assignees: @leonvanbokhorst

.cursor_rules → .cursorrules

@@ -1,20 +1,25 @@
+# Rules
+
 You are an AI expert specialized in developing simulations that model complex human behavior and group dynamics based on Narrative Field Theory. Your focus is on integrating LLMs for natural language-based decision making and interactions.
 
 Core Competencies:
+
 - Multi-agent systems and emergent behavior
 - Psychological modeling and group dynamics
 - LLM integration and prompt engineering
 - Distributed systems and event-driven architectures
 - Machine learning and neural networks
 
 Key Scientific Foundations:
+
 - Cognitive Science & Psychology
 - Complex Systems Theory
 - Social Network Analysis
 - Game Theory
 - Organizational Behavior
 
 Technical Stack:
+
 - Python (core language)
 - PyTorch (ML components)
 - Transformers (LLM integration)
@@ -23,6 +28,7 @@ Technical Stack:
 - Redis (state management)
 
 Code Quality Standards:
+
 1. Style and Formatting
    - Follow PEP 8 style guide
    - Use black for code formatting
@@ -76,6 +82,7 @@ Architecture Focus:
    - State-to-text conversion
 
 Development Workflow:
+
 1. Version Control
    - Git flow branching model
    - Semantic versioning
@@ -100,13 +107,15 @@ Development Workflow:
    - Performance benchmarks
 
 Key Patterns:
+
 - Loosely coupled components
 - Event-driven communication
 - Asynchronous processing
 - Modular design
 - Observable systems
 
 Best Practices:
+
 1. Clear separation of concerns
 2. Efficient state management
 3. Robust error handling

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,6 +12,7 @@ A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,15 +25,17 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
 
 **Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
 
 **Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/issue-.md

@@ -8,24 +8,31 @@ assignees: ''
 ---
 
 ## Title
+
 A clear and concise title for the issue.
 
 ## Description
+
 A detailed description of the issue.
 
 ## Steps to Reproduce
+
 1. Step one
 2. Step two
 3. Step three
 
 ## Expected Behavior
+
 What you expected to happen.
 
 ## Actual Behavior
+
 What actually happened.
 
 ## Screenshots/Logs
+
 Any relevant screenshots or logs.
 
 ## Environment
+
 Information about the environment where the issue occurred (e.g., OS, browser, version).

src/config.py

@@ -1,9 +1,19 @@
+"""
+Configuration module for the lab-politik application.
+
+This module contains global configuration variables and model-specific
+configurations for the application.
+"""
+
 from pathlib import Path
+from typing import Dict, Any
 
+# Application-wide constants
 APP_NAME: str = "lab-politik"
 IS_DEVELOPMENT: bool = True
 
-MODEL_CONFIGS = {
+# Model configuration dictionary
+MODEL_CONFIGS: Dict[str, Dict[str, Any]] = {
     "balanced": {
         "chat": {
             "path": Path(
@@ -32,3 +42,21 @@
         },
     },
 }
+
+def get_model_config(config_name: str = "balanced") -> Dict[str, Any]:
+    """
+    Retrieve the model configuration for a given configuration name.
+
+    Args:
+        config_name (str): The name of the configuration to retrieve.
+                           Defaults to "balanced".
+
+    Returns:
+        Dict[str, Any]: The model configuration dictionary.
+
+    Raises:
+        KeyError: If the specified config_name is not found in MODEL_CONFIGS.
+    """
+    if config_name not in MODEL_CONFIGS:
+        raise KeyError(f"Configuration '{config_name}' not found in MODEL_CONFIGS")
+    return MODEL_CONFIGS[config_name]

src/embedding_cache.py

@@ -1,28 +1,90 @@
 """Module for caching embeddings."""
 
 import hashlib
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Union
 
 
 class EmbeddingCache:
-    """Hash-based cache for storing embeddings."""
+    """
+    Hash-based cache for storing embeddings.
+
+    This class provides a simple key-value store for embeddings, using SHA-256 hashes
+    of the input text as keys. This ensures consistent lookup regardless of minor
+    text variations.
+
+    Attributes:
+        _cache (Dict[str, List[float]]): Internal storage for hashed key-value pairs.
+    """
 
     def __init__(self):
         self._cache: Dict[str, List[float]] = {}
 
     @staticmethod
     def get_stable_hash(text: str) -> str:
-        """Generate a stable hash for the given text."""
+        """
+        Generate a stable hash for the given text.
+
+        Args:
+            text (str): The input text to hash.
+
+        Returns:
+            str: A SHA-256 hash of the input text.
+        """
         return hashlib.sha256(text.encode()).hexdigest()
 
     def get(self, key: str) -> Optional[List[float]]:
-        """Retrieve an embedding from the cache using a hashed key."""
+        """
+        Retrieve an embedding from the cache using a hashed key.
+
+        Args:
+            key (str): The text key to look up.
+
+        Returns:
+            Optional[List[float]]: The stored embedding if found, None otherwise.
+        """
         return self._cache.get(self.get_stable_hash(key))
 
     def set(self, key: str, value: List[float]) -> None:
-        """Store an embedding in the cache using a hashed key."""
+        """
+        Store an embedding in the cache using a hashed key.
+
+        Args:
+            key (str): The text key to associate with the embedding.
+            value (List[float]): The embedding to store.
+        """
         self._cache[self.get_stable_hash(key)] = value
 
     def clear(self) -> None:
         """Clear all entries from the cache."""
         self._cache.clear()
+
+    def __len__(self) -> int:
+        """
+        Get the number of entries in the cache.
+
+        Returns:
+            int: The number of cached embeddings.
+        """
+        return len(self._cache)
+
+    def __contains__(self, key: str) -> bool:
+        """
+        Check if a key exists in the cache.
+
+        Args:
+            key (str): The text key to check.
+
+        Returns:
+            bool: True if the key exists in the cache, False otherwise.
+        """
+        return self.get_stable_hash(key) in self._cache
+
+    def update(self, items: Dict[str, List[float]]) -> None:
+        """
+        Update the cache with multiple key-value pairs.
+
+        Args:
+            items (Dict[str, List[float]]): A dictionary of text keys and their embeddings.
+        """
+        for key, value in items.items():
+            self.set(key, value)