semantic-buffer 0.1.2__py3-none-any.whl

semantic_buffer-0.1.2.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: semantic-buffer
+Version: 0.1.2
+Summary: A lightweight, local-first semantic memory buffer for AI agents with hybrid time-decay scoring.
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,memory,rag,semantic-search,sqlite
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'local'
+Description-Content-Type: text/markdown
+
+# semantic-buffer 🧠
+
+[![PyPI version](https://img.shields.io/pypi/v/semantic-buffer.svg)](https://pypi.org/project/semantic-buffer/)
+[![Python versions](https://img.shields.io/pypi/pyversions/semantic-buffer.svg)](https://pypi.org/project/semantic-buffer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, local-first semantic memory buffer for AI agents. It implements a hybrid scoring system that prioritizes memories based on **semantic relevance**, **importance**, and **exponential time-decay (recency)**.
+
+## 🌟 Features
+- **Local-first Vector Storage**: Simple SQLite-based vector storage with zero cloud dependencies or bulky database installations.
+- **Hybrid Scoring**: Combines cosine similarity, recency (exponential time decay), and importance weighting to retrieve the most contextual memories.
+- **Pluggable Embeddings**: Run lightweight model locally (`sentence-transformers`) or plug in any API (Gemini, OpenAI, Cohere).
+- **Agent Decorators**: `@remember` decorator automatically tracks function inputs, returns, and metadata in the background.
+
+## 🏗️ Architecture
+
+```text
+  [ Agent Action ] ──► ( @remember Decorator ) ──► [ SemanticBuffer ]
+                                                           │
+                                                  ( Generate Embeddings )
+                                                           │
+          [ LLM Prompt ] ◄── [ Ranked Top N Memories ] ◄── [ SQLite DB ]
+```
+
+## 🚀 Installation & Import Namespace
+
+> [!IMPORTANT]
+> **Install Name vs. Import Name Namespace**
+> - **Pip Install Name**: `semantic-buffer` (with hyphen)
+> - **Python Import Name**: `semanticbuffer` (no hyphens or underscores, e.g. `import semanticbuffer`)
+
+### 1. Minimal Installation (API Embedders)
+If you only plan to use external API models (Gemini, OpenAI, etc.) and want to keep dependencies lightweight:
+```bash
+pip install semantic-buffer
+```
+
+### 2. Local-First Installation (Offline CPU Models)
+If you want to use the default offline embeddings (`sentence-transformers` running locally on your CPU):
+```bash
+pip install "semantic-buffer[local]"
+```
+
+> [!WARNING]
+> If you instantiate `SemanticBuffer()` without passing an embedder, it defaults to using the local offline model. If you did not install the `[local]` extra, it will throw an `ImportError` requesting `sentence-transformers`.
+
+
+## ⚡ Quickstart
+
+```python
+from semanticbuffer import SemanticBuffer
+
+# 1. Initialize local memory buffer
+buffer = SemanticBuffer(db_path="my_memory.db")
+
+# 2. Add memories with importance scores
+buffer.add("User's favorite programming language is Python.", importance=0.9)
+buffer.add("It rained today in Paris.", importance=0.4)
+
+# 3. Retrieve relevant context dynamically
+memories = buffer.search("What coding preferences does the user have?", limit=1)
+print(memories[0]["content"])
+# Output: "User's favorite programming language is Python."
+```
+
+### Auto-Capture Agent Interactions with Decorators
+
+```python
+buffer = SemanticBuffer()
+
+@buffer.remember(importance=0.7)
+def run_web_search(query: str):
+    # Mocking search execution
+    return f"Results for {query}: Python is a versatile language."
+
+# Automatically logged to database
+run_web_search("Python info")
+```
+
+## ⚙️ Custom Embedders (OpenAI Example)
+You can easily swap out the local model for your preferred embedding API:
+
+```python
+from semanticbuffer import SemanticBuffer, BaseEmbedder
+
+class OpenAIEmbedder(BaseEmbedder):
+    def __init__(self, api_key):
+        from openai import OpenAI
+        self.client = OpenAI(api_key=api_key)
+
+    def embed_query(self, text: str):
+        res = self.client.embeddings.create(input=[text], model="text-embedding-3-small")
+        return res.data[0].embedding
+
+    def embed_documents(self, texts: list[str]):
+        return [self.embed_query(t) for t in texts]
+
+# Instantiate with custom embedder
+buffer = SemanticBuffer(embedder=OpenAIEmbedder(api_key="your-key"))
+```
+
+## 📄 License
+This project is licensed under the MIT License - see the LICENSE file for details.

semantic_buffer-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+semanticbuffer/__init__.py,sha256=YT8bGWicg-ZlrW1BfDu48jyA2PfDkJ45hkbJRmRXorI,205
+semanticbuffer/core.py,sha256=tPhLJfC23kG4C4LKM5mzyku0iFWsMp26B3n2MvVZt6E,5816
+semanticbuffer/database.py,sha256=pqAWm7cJ_xbOrTq3tkkYCW_6gS_QIS33-z6k1IYhazw,5247
+semanticbuffer/embeddings.py,sha256=ylIycMI1Rbyl6E9nI46UJsr_Q54Xis3PUOnjL-Tkr8A,3898
+semanticbuffer/scoring.py,sha256=IsflRJ5zs9UwLBq0VMsuT8-kPWhOsOCqdH_Pui2XlFY,2345
+semantic_buffer-0.1.2.dist-info/METADATA,sha256=Z58OHGlp5REk4KZFlm2oP6kDPfzoSu_SoQtE_BmVu9A,5047
+semantic_buffer-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+semantic_buffer-0.1.2.dist-info/licenses/LICENSE,sha256=v5sKwAPGsjHXh71ki03x99TjxEfzrba8oPGVigUvf-w,1063
+semantic_buffer-0.1.2.dist-info/RECORD,,

semantic_buffer-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

semantic_buffer-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mastan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semanticbuffer/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.1.2"
+
+from .core import SemanticBuffer
+from .embeddings import BaseEmbedder, CustomEmbedder, LocalEmbedder
+
+__all__ = ["SemanticBuffer", "BaseEmbedder", "LocalEmbedder", "CustomEmbedder"]

semanticbuffer/core.py

@@ -0,0 +1,154 @@
+import functools
+from typing import Any, Callable, Dict, List, Optional
+
+from .database import MemoryDB
+from .embeddings import BaseEmbedder, LocalEmbedder
+from .scoring import calculate_hybrid_score, cosine_similarity
+
+
+class SemanticBuffer:
+    """Core memory coordinator for managing semantic retrieval and logging.
+
+    Ties together local SQLite database storage, embedding generators, and
+    hybrid relevancy scoring logic.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "memory.db",
+        embedder: Optional[BaseEmbedder] = None,
+        recency_weight: float = 0.4,
+        decay_rate: float = 0.005,
+        importance_weight: float = 0.3,
+    ):
+        """Initializes the SemanticBuffer instance.
+
+        Args:
+            db_path (str, optional): Path to the SQLite storage file.
+                Defaults to "memory.db".
+            embedder (BaseEmbedder, optional): The vector embedding model backend.
+                If None, uses a LocalEmbedder defaults to sentence-transformers.
+            recency_weight (float, optional): Weight score contribution of
+                time decay. Defaults to 0.4.
+            decay_rate (float, optional): Exponential decay rate per hour.
+                Defaults to 0.005.
+            importance_weight (float, optional): Weight score contribution of
+                importance. Defaults to 0.3.
+        """
+        self.db = MemoryDB(db_path)
+        self.embedder = embedder or LocalEmbedder()
+        self.recency_weight = recency_weight
+        self.decay_rate = decay_rate
+        self.importance_weight = importance_weight
+
+    def add(
+        self,
+        text: str,
+        importance: float = 0.5,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Saves a new memory into the local vector buffer.
+
+        Args:
+            text (str): Content text to remember.
+            importance (float, optional): Manual importance weight (0.0 to 1.0).
+                Defaults to 0.5.
+            metadata (Dict[str, Any], optional): Contextual key-value metrics.
+                Defaults to None.
+
+        Returns:
+            int: The inserted record row ID.
+        """
+        embedding = self.embedder.embed_query(text)
+        return self.db.insert_memory(text, embedding, importance, metadata)
+
+    def search(self, query: str, limit: int = 5) -> List[Dict[str, Any]]:
+        """Searches and returns memories sorted by their hybrid relevance score.
+
+        Args:
+            query (str): The search phrase.
+            limit (int, optional): Maximum count of memories to return.
+                Defaults to 5.
+
+        Returns:
+            List[Dict[str, Any]]: Ranked results (highest score first) without the
+                raw embedding vectors to keep the payloads lightweight.
+        """
+        query_vector = self.embedder.embed_query(query)
+        memories = self.db.fetch_all_memories()
+
+        if not memories:
+            return []
+
+        scored_memories = []
+        for mem in memories:
+            semantic_sim = cosine_similarity(query_vector, mem["embedding"])
+            hybrid_score = calculate_hybrid_score(
+                semantic_sim=semantic_sim,
+                created_at=mem["created_at"],
+                importance=mem["importance"],
+                recency_weight=self.recency_weight,
+                decay_rate=self.decay_rate,
+                importance_weight=self.importance_weight,
+            )
+            # Remove embedding from return payloads to keep output clean
+            result = mem.copy()
+            del result["embedding"]
+            result["score"] = hybrid_score
+            scored_memories.append(result)
+
+        # Sort descending by score
+        scored_memories.sort(key=lambda x: x["score"], reverse=True)
+        return scored_memories[:limit]
+
+    def clear(self):
+        """Removes all memories from the storage database table."""
+        self.db.clear()
+
+    def remember(
+        self,
+        importance: float = 0.5,
+        capture_inputs: bool = True,
+        capture_output: bool = True,
+        summary_extractor: Optional[Callable[[Any, Any, tuple, dict], str]] = None,
+    ):
+        """Decorator to automatically log function calls and outputs to the buffer.
+
+        Args:
+            importance (float, optional): Floating importance score for the call record.
+                Defaults to 0.5.
+            capture_inputs (bool, optional): Logs the values of function arguments.
+                Defaults to True.
+            capture_output (bool, optional): Logs the returned function output.
+                Defaults to True.
+            summary_extractor (Callable, optional): Custom function to parse inputs
+                and returns and convert them into a structured log text string.
+        """
+
+        def decorator(func):
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                result = func(*args, **kwargs)
+
+                # Extract description of what happened
+                if summary_extractor:
+                    content = summary_extractor(result, func.__name__, args, kwargs)
+                else:
+                    parts = [f"Function '{func.__name__}' was called."]
+                    if capture_inputs:
+                        parts.append(f"Arguments: args={args}, kwargs={kwargs}")
+                    if capture_output:
+                        parts.append(f"Returned output: {result}")
+                    content = "\n".join(parts)
+
+                # Save to database
+                self.add(
+                    text=content,
+                    importance=importance,
+                    metadata={"function": func.__name__, "source": "decorator"},
+                )
+                return result
+
+            return wrapper
+
+        return decorator

semanticbuffer/database.py

@@ -0,0 +1,150 @@
+import json
+import sqlite3
+import struct
+from datetime import datetime
+from typing import Any, Dict, List
+
+
+class MemoryDB:
+    """Manages the local SQLite database for storing and retrieving agent memories.
+
+    This class handles the creation of schemas, serialization/deserialization of
+    embeddings into SQLite BLOB formats, and standard database operations.
+    """
+
+    def __init__(self, db_path: str):
+        """Initializes the database connection and builds schemas if not present.
+
+        Args:
+            db_path (str): Filepath to the SQLite database.
+        """
+        self.db_path = db_path
+        self._conn = None
+        self._init_db()
+
+    def _get_connection(self):
+        """Helper to get a thread-safe connection to the SQLite database.
+
+        Returns:
+            sqlite3.Connection: The active SQLite connection object.
+        """
+        return sqlite3.connect(self.db_path)
+
+    def _init_db(self):
+        """Creates the memories table if it does not already exist."""
+        with self._get_connection() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    content TEXT NOT NULL,
+                    embedding BLOB NOT NULL,
+                    importance REAL DEFAULT 0.5,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    metadata_json TEXT
+                )
+            """)
+            conn.commit()
+
+    @staticmethod
+    def _vector_to_blob(vector: List[float]) -> bytes:
+        """Packs a list of python floats into binary bytes.
+
+        Args:
+            vector (List[float]): List of floats to serialize.
+
+        Returns:
+            bytes: Standard packed binary float data (64-bit double precision).
+        """
+        return struct.pack(f"{len(vector)}d", *vector)
+
+    @staticmethod
+    def _blob_to_vector(blob: bytes) -> List[float]:
+        """Unpacks binary bytes back to a list of python floats.
+
+        Args:
+            blob (bytes): Packed binary data.
+
+        Returns:
+            List[float]: Restored float vector.
+        """
+        num_floats = len(blob) // 8
+        return list(struct.unpack(f"{num_floats}d", blob))
+
+    def insert_memory(
+        self,
+        content: str,
+        embedding: List[float],
+        importance: float,
+        metadata: Dict[str, Any] = None,
+    ) -> int:
+        """Inserts a new memory record into the SQLite database.
+
+        Args:
+            content (str): The raw text contents of the memory.
+            embedding (List[float]): Multi-dimensional semantic embedding vector.
+            importance (float): Floating-point score between 0.0 and 1.0.
+            metadata (Dict[str, Any], optional): Key-value properties to associate.
+
+        Returns:
+            int: The unique row ID of the inserted record.
+        """
+        metadata_str = json.dumps(metadata) if metadata else None
+        vector_blob = self._vector_to_blob(embedding)
+
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            query = (
+                "INSERT INTO memories "
+                "(content, embedding, importance, metadata_json) "
+                "VALUES (?, ?, ?, ?)"
+            )
+            cursor.execute(query, (content, vector_blob, importance, metadata_str))
+            conn.commit()
+            return cursor.lastrowid
+
+    def fetch_all_memories(self) -> List[Dict[str, Any]]:
+        """Queries and retrieves all saved memories from the database.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries representing memories,
+                including id, content, embedding, importance, created_at, and metadata.
+        """
+        with self._get_connection() as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+            query = (
+                "SELECT id, content, embedding, importance, "
+                "created_at, metadata_json FROM memories"
+            )
+            cursor.execute(query)
+            rows = cursor.fetchall()
+
+            memories = []
+            for row in rows:
+                created_at_val = row["created_at"]
+                if "T" in created_at_val:
+                    parsed_time = datetime.fromisoformat(created_at_val)
+                else:
+                    parsed_time = datetime.strptime(created_at_val, "%Y-%m-%d %H:%M:%S")
+
+                memories.append(
+                    {
+                        "id": row["id"],
+                        "content": row["content"],
+                        "embedding": self._blob_to_vector(row["embedding"]),
+                        "importance": row["importance"],
+                        "created_at": parsed_time,
+                        "metadata": (
+                            json.loads(row["metadata_json"])
+                            if row["metadata_json"]
+                            else {}
+                        ),
+                    }
+                )
+            return memories
+
+    def clear(self):
+        """Deletes all memory entries from the table."""
+        with self._get_connection() as conn:
+            conn.execute("DELETE FROM memories")
+            conn.commit()

semanticbuffer/embeddings.py

@@ -0,0 +1,131 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class BaseEmbedder(ABC):
+    """Abstract base class for semantic text embedders.
+
+    All custom embedding adapters (e.g. OpenAI, Gemini, Cohere) must
+    inherit from this class and implement the abstract methods.
+    """
+
+    @abstractmethod
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Embed a list of text strings into a list of vector floats.
+
+        Args:
+            texts (List[str]): List of texts to embed.
+
+        Returns:
+            List[List[float]]: List of float vectors corresponding to each text.
+        """
+        pass
+
+    @abstractmethod
+    def embed_query(self, text: str) -> List[float]:
+        """Embed a single query string into a vector float.
+
+        Args:
+            text (str): Query string to embed.
+
+        Returns:
+            List[float]: The semantic embedding vector.
+        """
+        pass
+
+
+class LocalEmbedder(BaseEmbedder):
+    """A local CPU-friendly embedder using sentence-transformers.
+
+    Loads the models lazily on first access to keep imports fast.
+    """
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        """Initializes the LocalEmbedder with a target model.
+
+        Args:
+            model_name (str, optional): Hugging Face sentence-transformers model.
+                Defaults to "all-MiniLM-L6-v2".
+        """
+        self.model_name = model_name
+        self._model = None
+
+    @property
+    def model(self):
+        """Loads and caches the local SentenceTransformer model.
+
+        Raises:
+            ImportError: If sentence-transformers package is missing.
+        """
+        if self._model is None:
+            try:
+                from sentence_transformers import SentenceTransformer
+            except ImportError:
+                raise ImportError(
+                    "sentence-transformers is required for local embeddings. "
+                    "Install it using `pip install semantic-buffer[local]`."
+                )
+            self._model = SentenceTransformer(self.model_name)
+        return self._model
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Generates vectors for a list of documents.
+
+        Args:
+            texts (List[str]): Input documents.
+
+        Returns:
+            List[List[float]]: Generated float vectors.
+        """
+        embeddings = self.model.encode(texts, convert_to_numpy=True)
+        return embeddings.tolist()
+
+    def embed_query(self, text: str) -> List[float]:
+        """Generates a vector for a single query.
+
+        Args:
+            text (str): Query string.
+
+        Returns:
+            List[float]: Generated float vector.
+        """
+        embedding = self.model.encode(text, convert_to_numpy=True)
+        return embedding.tolist()
+
+
+class CustomEmbedder(BaseEmbedder):
+    """Wraps any standard user-provided function that generates embeddings.
+
+    Useful when you want to pass a simple inline callable or lambda function.
+    """
+
+    def __init__(self, embed_fn):
+        """Initializes the CustomEmbedder with a callable.
+
+        Args:
+            embed_fn (Callable): Function that accepts a list of strings
+                and returns a list of float vectors.
+        """
+        self.embed_fn = embed_fn
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Passes texts to the custom embedding function.
+
+        Args:
+            texts (List[str]): Input texts.
+
+        Returns:
+            List[List[float]]: Generated float vectors.
+        """
+        return self.embed_fn(texts)
+
+    def embed_query(self, text: str) -> List[float]:
+        """Passes query to the custom embedding function.
+
+        Args:
+            text (str): Input query.
+
+        Returns:
+            List[float]: Generated float vector.
+        """
+        return self.embed_fn([text])[0]

semanticbuffer/scoring.py

@@ -0,0 +1,73 @@
+import math
+from datetime import datetime, timezone
+from typing import List
+
+import numpy as np
+
+
+def cosine_similarity(v1: List[float], v2: List[float]) -> float:
+    """Calculates the cosine similarity metric between two float vectors.
+
+    Args:
+        v1 (List[float]): First vector.
+        v2 (List[float]): Second vector.
+
+    Returns:
+        float: Cosine similarity score between -1.0 and 1.0 (0.0 if zero vectors).
+    """
+    a = np.array(v1)
+    b = np.array(v2)
+    dot = np.dot(a, b)
+    norm_a = np.linalg.norm(a)
+    norm_b = np.linalg.norm(b)
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return float(dot / (norm_a * norm_b))
+
+
+def calculate_hybrid_score(
+    semantic_sim: float,
+    created_at: datetime,
+    importance: float,
+    recency_weight: float = 0.5,
+    decay_rate: float = 0.01,
+    importance_weight: float = 0.3,
+) -> float:
+    """Computes a hybrid retrieval score combining relevance, recency, and importance.
+
+    Implements the standard Generative Agents memory retrieval algorithm:
+    Score = (1.0 - recency_weight - importance_weight) * Similarity
+            + recency_weight * RecencyScore
+            + importance_weight * ImportanceScore
+
+    RecencyScore = e^(-decay_rate * age_in_hours)
+
+    Args:
+        semantic_sim (float): Cosine similarity value between 0.0 and 1.0.
+        created_at (datetime): Timestamp when the memory was stored.
+        importance (float): Floating-point score between 0.0 and 1.0.
+        recency_weight (float, optional): Score weighting for recency.
+            Defaults to 0.5.
+        decay_rate (float, optional): Exponential decay rate per hour.
+            Defaults to 0.01.
+        importance_weight (float, optional): Score weighting for importance.
+            Defaults to 0.3.
+
+    Returns:
+        float: Normalized hybrid retrieval score.
+    """
+    # Calculate age in hours
+    now_utc = datetime.now(timezone.utc).replace(tzinfo=None)
+    age_seconds = (now_utc - created_at).total_seconds()
+    age_hours = max(0.0, age_seconds / 3600.0)
+
+    # Exponential decay for recency
+    recency_score = math.exp(-decay_rate * age_hours)
+
+    # Combined score
+    score = (
+        (1.0 - recency_weight - importance_weight) * semantic_sim
+        + recency_weight * recency_score
+        + importance_weight * importance
+    )
+    return score