versionhq 1.1.12.1__py3-none-any.whl → 1.1.12.2__py3-none-any.whl

versionhq/__init__.py

@@ -8,25 +8,64 @@ from versionhq.agent.model import Agent
 from versionhq.clients.customer.model import Customer
 from versionhq.clients.product.model import Product, ProductProvider
 from versionhq.clients.workflow.model import MessagingWorkflow, MessagingComponent
-from versionhq.task.model import Task, TaskOutput
-from versionhq.team.model import Team, TeamOutput
-from versionhq.tool.model import Tool
+from versionhq.knowledge.model import Knowledge, KnowledgeStorage
+from versionhq.knowledge.source import PDFKnowledgeSource, CSVKnowledgeSource, JSONKnowledgeSource, TextFileKnowledgeSource, ExcelKnowledgeSource, StringKnowledgeSource
+from versionhq.knowledge.source_docling import DoclingSource
+from versionhq.task.model import Task, TaskOutput, ConditionalTask, ResponseField
+from versionhq.task.evaluate import Evaluation, EvaluationItem
+from versionhq.team.model import Team, TeamOutput, Formation, TeamMember, TaskHandlingProcess
+from versionhq.tool.model import Tool, ToolSet
+from versionhq.tool.cache_handler import CacheHandler
+from versionhq.tool.tool_handler import ToolHandler
 from versionhq.tool.composio_tool import ComposioHandler
+from versionhq.memory.contextual_memory import ContextualMemory
+from versionhq.memory.model import ShortTermMemory,LongTermMemory, UserMemory, MemoryItem
 
 
-__version__ = "1.1.12.1"
+
+__version__ = "1.1.12.2"
 __all__ = [
     "Agent",
+
     "Customer",
     "Product",
     "ProductProvider",
     "MessagingWorkflow",
     "MessagingComponent",
-    "LLM",
+
+    "Knowledge",
+    "KnowledgeStorage",
+    "PDFKnowledgeSource",
+    "CSVKnowledgeSource",
+    "JSONKnowledgeSource",
+    "TextFileKnowledgeSource",
+    "ExcelKnowledgeSource",
+    "StringKnowledgeSource",
+    "DoclingSource",
+
     "Task",
     "TaskOutput",
+    "ConditionalTask",
+    "ResponseField",
+
+    "Evaluation",
+    "EvaluationItem",
+
     "Team",
     "TeamOutput",
+    "Formation",
+    "TeamMember",
+    "TaskHandlingProcess",
+
     "Tool",
-    "ComposioHandler"
+    "ToolSet",
+    "CacheHandler",
+    "ToolHandler",
+    "ComposioHandler",
+
+    "ContextualMemory",
+    "ShortTermMemory",
+    "LongTermMemory",
+    "UserMemory",
+    "MemoryItem"
 ]

versionhq/_utils/__init__.py

@@ -0,0 +1,3 @@
+from versionhq._utils.logger import Logger
+from versionhq._utils.process_config import process_config
+from versionhq._utils.usage_metrics import UsageMetrics

versionhq/agent/inhouse_agents.py

@@ -3,29 +3,39 @@ from versionhq.llm.model import DEFAULT_MODEL_NAME
 
 """
 In-house agents to be called across the project.
-[Rules] agents' names and roles start with `vhq_`.
+[Rules] In house agents have names and roles that start with `vhq_`. No customization allowed by client.
 """
 
 vhq_client_manager = Agent(
     role="vhq-Client Manager",
     goal="Efficiently communicate with the client on the task progress",
-    llm=DEFAULT_MODEL_NAME
+    llm=DEFAULT_MODEL_NAME,
+    use_memory=True,
 )
 
+
 vhq_task_evaluator = Agent(
     role="vhq-Task Evaluator",
     goal="score the output according to the given evaluation criteria.",
     llm=DEFAULT_MODEL_NAME,
     llm_config=dict(top_p=0.8, top_k=30, max_tokens=5000, temperature=0.9),
     maxit=1,
-    max_retry_limit=1
+    max_retry_limit=1,
+    use_memory=True # refer past eval records of similar tasks
 )
 
+
 vhq_formation_planner = Agent(
     role="vhq-Formation Planner",
     goal="Plan a formation of agents based on the given task descirption.",
     llm="gemini/gemini-2.0-flash-exp",
     llm_config=dict(top_p=0.8, top_k=30, temperature=0.9),
     maxit=1,
-    max_retry_limit=1
+    max_retry_limit=1,
+    knowledge_sources=[
+        "Solo is a formation where a single agent with tools, knowledge, and memory handles tasks indivudually. When self-learning mode is on - it will turn into Random formation. Typical usecase is an email agent drafts promo message for the given audience using their own knowledge.",
+        "Supervising is a formation where the leader agent gives directions, while sharing its knowledge and memory with subbordinates.Subordinates can be solo agents or networks. Typical usecase is that the leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents.",
+        "Network is a formation where multple agents can share tasks, knowledge, and memory among network members without hierarchy. Typical usecase is that an email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. ",
+        "Random is a formation where a single agent handles tasks, asking help from other agents without sharing its memory or knowledge. Typical usecase is that an email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other customer clusters, or an agent calls the external, third party agent to deploy the campaign. ",
+    ]
 )

versionhq/agent/model.py

@@ -1,6 +1,5 @@
 import os
 import uuid
-import datetime
 from typing import Any, Dict, List, Optional, TypeVar, Callable, Type
 from typing_extensions import Self
 from dotenv import load_dotenv
@@ -353,7 +352,7 @@ class Agent(BaseModel):
     @model_validator(mode="after")
     def set_up_memory(self) -> Self:
         """
-        Set up memories: stm, um
+        Set up memories: stm, ltm, and um
         """
 
         if self.use_memory == True:

versionhq/agent/rpm_controller.py

@@ -5,7 +5,7 @@ from typing_extensions import Self
 
 from pydantic import BaseModel, Field, PrivateAttr, model_validator
 
-from versionhq._utils.logger import Logger
+from versionhq._utils import Logger
 
 
 class RPMController(BaseModel):

versionhq/clients/product/model.py

@@ -56,7 +56,6 @@ class ProductProvider(ABC, BaseModel):
         return self
 
 
-
 class Product(BaseModel):
     """
     A class to store product information used to create outbound

versionhq/knowledge/__init__.py

@@ -0,0 +1,22 @@
+from versionhq.knowledge.model import Knowledge, KnowledgeStorage
+from versionhq.knowledge.source import (
+    CSVKnowledgeSource,
+    ExcelKnowledgeSource,
+    PDFKnowledgeSource,
+    TextFileKnowledgeSource,
+    JSONKnowledgeSource,
+    StringKnowledgeSource
+)
+from versionhq.knowledge.source_docling import DoclingSource
+
+__all__ = [
+    "Knowledge",
+    "KnowledgeStorage",
+    "DoclingSource",
+    "CSVKnowledgeSource",
+    "ExcelKnowledgeSource",
+    "PDFKnowledgeSource",
+    "TextFileKnowledgeSource",
+    "JSONKnowledgeSource",
+    "StringKnowledgeSource"
+]

versionhq/knowledge/model.py

@@ -1,5 +1,3 @@
-import os
-from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 

versionhq/knowledge/source.py

@@ -280,7 +280,6 @@ class PDFKnowledgeSource(BaseFileKnowledgeSource):
 
 
 
-
 class CSVKnowledgeSource(BaseFileKnowledgeSource):
     """
     A knowledge source class that stores and queries CSV file content using embeddings.

versionhq/memory/model.py

@@ -1,7 +1,53 @@
+import datetime
 from typing import Any, Dict, List, Optional
 
 from versionhq.storage.rag_storage import RAGStorage
 from versionhq.storage.ltm_sqlite_storage import LTMSQLiteStorage
+from versionhq._utils.logger import Logger
+
+
+class MemoryData:
+    """
+    A class to store structured data to store in the memory.
+    """
+    def __init__(
+        self,
+        agent: Optional[str] = None, # task execution agent (core)
+        task_description: Optional[str] = None,
+        task_output: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None
+    ):
+        self.agent = agent
+        self.task_description = task_description
+        self.task_output = task_output
+
+        if config:
+            for k, v in config.items():
+                setattr(self, k, str(v))
+
+
+
+class MemoryMetadata:
+    """
+     A class to store structured metadata to store in the memory.
+    """
+
+    def __init__(
+        self,
+        eval_criteria: Optional[str] = None,
+        score: Optional[int | float] = None,
+        suggestion: Optional[str] = None,
+        eval_by: Optional[str] = None, # task evaluator agent
+        config: Optional[Dict[str, Any]] = None
+    ):
+        self.eval_criteria = eval_criteria
+        self.score = score
+        self.suggestion = suggestion
+        self.eval_by = eval_by
+
+        if config:
+            for k, v in config.items():
+                setattr(self, k, str(v))
 
 
 class Memory:
@@ -13,28 +59,46 @@ class Memory:
         self.storage = storage
 
 
-    def save(self, value: Any, metadata: Optional[Dict[str, Any]] = None, agent: Optional[str] = None) -> None:
-        metadata = metadata or {}
+    def save(
+            self,
+            data: MemoryData | Dict[str, Any],
+            metadata: Optional[MemoryMetadata | Dict[str, Any]] = None,
+            agent: Optional[str] = None
+        ) -> None:
+
+        """
+        Create a dict for data and metadata without empty values before storing them in the given storage.
+        """
+
+        if not data:
+            Logger(verbose=True).log(level="error", message="Missing data to store. Add either dict or MemoryData object", color="red")
+            return None
 
-        if agent:
-            metadata["agent"] = agent
-        self.storage.save(value, metadata)
+        metadata_dict = metadata if isinstance(metadata, dict) else metadata.__dict__ if isinstance(metadata, MemoryMetadata) else dict()
+        metadata_dict = {k: v for k, v in metadata_dict.items() if v} # remove empty values
+        data_dict = data if isinstance(data, dict) else data.__dict__ if isinstance(data, MemoryData) else dict()
+        data_dict = {k: v for k, v in data_dict.items() if v}
+
+        if agent and data_dict["agent"] is None:
+            data_dict["agent"] = agent
+
+        if metadata_dict:
+            self.storage.save(data=data_dict, metadata=metadata_dict)
+        else:
+            self.storage.save(data=data_dict)
 
 
     def search(self, query: str, limit: int = 3, score_threshold: float = 0.35) -> List[Any]:
         return self.storage.search(query=query, limit=limit, score_threshold=score_threshold)
 
 
+class MemoryItem:
+    """
+    A class to store item to be saved in either long term memory or short term memory.
+    """
 
-class ShortTermMemoryItem:
-    def __init__(
-        self,
-        data: Any,
-        agent: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ):
+    def __init__(self, data: MemoryData = None, metadata: Optional[MemoryMetadata] = None):
         self.data = data
-        self.agent = agent
         self.metadata = metadata if metadata is not None else {}
 
 
@@ -70,12 +134,22 @@ class ShortTermMemory(Memory):
         super().__init__(storage)
 
 
-    def save(self, value: Any, metadata: Optional[Dict[str, Any]] = None, agent: Optional[str] = None) -> None:
-        item = ShortTermMemoryItem(data=value, metadata=metadata, agent=agent)
+    def save(
+            self,
+            task_description: str = None,
+            task_output: str = None,
+            agent: Optional[str] = None,
+            data: Optional[MemoryData] = None,
+            metadata: Optional[MemoryMetadata] = None
+        ) -> None:
+
+        data = data if data else MemoryData(task_description=task_description, task_output=task_output, agent=agent)
+        item = MemoryItem(data=data, metadata=metadata)
+
         if self.memory_provider == "mem0":
-            item.data = f"Remember the following insights from Agent run: {item.data}"
+            item.data.task_output = f"Remember the following insights from Agent run: {item.data.task_output}"
 
-        super().save(value=item.data, metadata=item.metadata, agent=item.agent)
+        super().save(data=item.data.__dict__, metadata=item.metadata.__dict__ if item.metadata else {})
 
 
     def search(self, query: str, limit: int = 3, score_threshold: float = 0.35,):
@@ -89,29 +163,11 @@ class ShortTermMemory(Memory):
             raise Exception(f"An error occurred while resetting the short-term memory: {str(e)}")
 
 
-
-class LongTermMemoryItem:
-    def __init__(
-        self,
-        agent: str,
-        task: str,
-        datetime: str,
-        quality: Optional[int | float] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ):
-        self.task = task
-        self.agent = agent
-        self.quality = quality
-        self.datetime = datetime
-        self.metadata = metadata if metadata is not None else {}
-
-
-
 class LongTermMemory(Memory):
     """
     A class for managing cross runs data related to overall task executions.
     - Type: ltm
-    - Storage: LTMSQLiteStorage
+    - Storage: LTMSQLiteStorage | RAGStorage
     """
 
     def __init__(self, storage=None, path=None):
@@ -121,19 +177,25 @@ class LongTermMemory(Memory):
         super().__init__(storage)
 
 
-    def save(self, item: LongTermMemoryItem) -> None:
-        metadata = item.metadata
-        metadata.update({ "agent": item.agent })
-        self.storage.save(
-            task_description=item.task,
-            score=metadata["quality"],
-            metadata=metadata,
-            datetime=item.datetime,
-        )
+    def save(
+            self,
+            task_description: str = None,
+            task_output: str = None,
+            agent: Optional[str] = None,
+            data: Optional[MemoryData] = None,
+            metadata: Optional[MemoryMetadata] = None
+        ) -> None:
+
+        data = data if data else MemoryData(task_description=task_description, task_output=task_output, agent=agent)
+        item = MemoryItem(data=data, metadata=metadata)
+        super().save(data=item.data, metadata=item.metadata)
 
 
-    def search(self, task: str, latest_n: int = 3) -> List[Dict[str, Any]]:
-        return self.storage.load(task, latest_n)
+    def search(self, query: str, latest_n: int = 3) -> List[Dict[str, Any]]:
+        """
+        Query the storage and return the results up to latest_n.
+        """
+        return self.storage.load(query=query, latest_n=latest_n)
 
 
     def reset(self) -> None:

versionhq/storage/ltm_sqlite_storage.py

@@ -1,4 +1,5 @@
 import json
+import datetime
 import sqlite3
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -27,88 +28,77 @@ class LTMSQLiteStorage:
         """
         Initializes the SQLite database and creates LTM table
         """
+
         try:
             with sqlite3.connect(self.db_path) as conn:
                 cursor = conn.cursor()
                 cursor.execute(
-                    """
+                """
                     CREATE TABLE IF NOT EXISTS long_term_memories (
                         id INTEGER PRIMARY KEY AUTOINCREMENT,
-                        task_description TEXT,
-                        metadata TEXT,
-                        datetime TEXT,
-                        score REAL
+                        datetime REAL,
+                        data TEXT,
+                        metadata TEXT
                     )
                 """
                 )
-
                 conn.commit()
 
         except sqlite3.Error as e:
-            self._logger.log(
-                level="error",
-                message=f"MEMORY ERROR: An error occurred during database initialization: {str(e)}",
-                color="red",
-            )
+            self._logger.log(level="error", message=f"MEMORY ERROR: An error occurred during database initialization: {str(e)}", color="red")
+
 
-    def save(self, task_description: str, metadata: Dict[str, Any], datetime: str, score: int | float) -> None:
+    def save(self, data: Dict[str, Any] | str, metadata: Optional[Dict[str, Any]] = {}) -> None:
         """
         Saves data to the LTM table with error handling.
         """
+        data = data if isinstance(data, dict) else dict(data=data)
+
         try:
             with sqlite3.connect(self.db_path) as conn:
                 cursor = conn.cursor()
                 cursor.execute(
-                    """
-                INSERT INTO long_term_memories (task_description, metadata, datetime, score)
-                VALUES (?, ?, ?, ?)
+            """
+                INSERT INTO long_term_memories (datetime, data, metadata)
+                VALUES (?, ?, ?)
             """,
-                    (task_description, json.dumps(metadata), datetime, score),
+                    (datetime.datetime.now().timestamp(), json.dumps(data), json.dumps(metadata)),
                 )
                 conn.commit()
         except sqlite3.Error as e:
-            self._logger.log(
-                level="error",
-                message=f"MEMORY ERROR: An error occurred while saving to LTM: {str(e)}",
-                color="red",
-            )
+            self._logger.log(level="error", message=f"MEMORY ERROR: An error occurred while saving to LTM: {str(e)}", color="red")
 
 
-    def load(self, task_description: str, latest_n: int) -> Optional[List[Dict[str, Any]]]:
+    def load(self, query: str, latest_n: int) -> Optional[List[Dict[str, Any]]]:
         """
-        Queries the LTM table by task description with error handling.
+        Queries the data row in the storage with error handling.
         """
         try:
             with sqlite3.connect(self.db_path) as conn:
                 cursor = conn.cursor()
                 cursor.execute(
-                    f"""
-                    SELECT metadata, datetime, score
+                f"""
+                    SELECT datetime, data, metadata
                     FROM long_term_memories
-                    WHERE task_description = ?
-                    ORDER BY datetime DESC, score ASC
+                    WHERE data LIKE '%{query}%'
+                    ORDER BY datetime
                     LIMIT {latest_n}
-                """,
-                    (task_description,),
+                """
                 )
                 rows = cursor.fetchall()
                 if rows:
                     return [
                         {
-                            "metadata": json.loads(row[0]),
-                            "datetime": row[1],
-                            "score": row[2],
+                            "datetime": row[0],
+                            "data": json.loads(row[1]),
+                            "metadata": json.loads(row[2]),
                         }
                         for row in rows
                     ]
 
         except sqlite3.Error as e:
-            self._logger.log(
-                level="error",
-                message=f"MEMORY ERROR: An error occurred while querying LTM: {e}",
-                color="red",
-            )
-        return None
+            self._logger.log(level="error", message=f"MEMORY ERROR: An error occurred while querying LTM: {e}",color="red")
+            return None
 
 
     def reset(self) -> None:
@@ -123,9 +113,5 @@ class LTMSQLiteStorage:
                 conn.commit()
 
         except sqlite3.Error as e:
-            self._logger.log(
-                level="error",
-                message=f"MEMORY ERROR: An error occurred while deleting all rows in LTM: {str(e)}",
-                color="red",
-            )
+            self._logger.log(level="error", message=f"MEMORY ERROR: An error occurred while deleting all rows in LTM: {str(e)}", color="red")
         return None

versionhq/storage/mem0_storage.py

@@ -47,7 +47,7 @@ class Mem0Storage(Storage):
         return role.replace("\n", "").replace(" ", "_").replace("/", "_")
 
 
-    def save(self, value: Any, metadata: Dict[str, Any]) -> None:
+    def save(self, value: Dict[str, Any] | str, metadata: Dict[str, Any]) -> None:
         user_id = self._get_user_id()
         agent_name = self._get_agent_name()
 

versionhq/storage/rag_storage.py

@@ -163,11 +163,32 @@ class RAGStorage(BaseRAGStorage):
         return f"{base_path}/{file_name}"
 
 
-    def save(self, value: Any, metadata: Dict[str, Any]) -> None:
+    def _create_default_embedding_function(self):
+        from chromadb.utils.embedding_functions.openai_embedding_function import (
+            OpenAIEmbeddingFunction,
+        )
+
+        return OpenAIEmbeddingFunction(
+            api_key=os.getenv("OPENAI_API_KEY"), model_name="text-embedding-3-small"
+        )
+
+
+    def _generate_embedding(self, text: str, metadata: Optional[Dict[str, Any]]) -> None:
+        if not hasattr(self, "app") or not hasattr(self, "collection"):
+            self._initialize_app()
+
+        if metadata:
+            self.collection.add(documents=[text], metadatas=[metadata, ], ids=[str(uuid.uuid4())])
+
+        else:
+            self.collection.add(documents=[text], ids=[str(uuid.uuid4())])
+
+
+    def save(self, data: Dict[str, Any] | str, metadata: Optional[Dict[str, Any]] = dict()) -> None:
         if not hasattr(self, "app") or not hasattr(self, "collection"):
             self._initialize_app()
         try:
-            self._generate_embedding(value, metadata)
+            self._generate_embedding(text=str(data), metadata=metadata)
         except Exception as e:
             logging.error(f"Error during {self.type} save: {str(e)}")
 
@@ -197,17 +218,6 @@ class RAGStorage(BaseRAGStorage):
             return []
 
 
-    def _generate_embedding(self, text: str, metadata: Dict[str, Any]) -> None:
-        if not hasattr(self, "app") or not hasattr(self, "collection"):
-            self._initialize_app()
-
-        self.collection.add(
-            documents=[text],
-            metadatas=[metadata or {}],
-            ids=[str(uuid.uuid4())],
-        )
-
-
     def reset(self) -> None:
         try:
             if self.app:
@@ -220,12 +230,3 @@ class RAGStorage(BaseRAGStorage):
                 pass
             else:
                 raise Exception(f"An error occurred while resetting the {self.type} memory: {e}")
-
-    def _create_default_embedding_function(self):
-        from chromadb.utils.embedding_functions.openai_embedding_function import (
-            OpenAIEmbeddingFunction,
-        )
-
-        return OpenAIEmbeddingFunction(
-            api_key=os.getenv("OPENAI_API_KEY"), model_name="text-embedding-3-small"
-        )

versionhq/storage/task_output_storage.py

@@ -7,7 +7,7 @@ from versionhq._utils.logger import Logger
 from versionhq.storage.utils import fetch_db_storage_path
 
 storage_path = fetch_db_storage_path()
-default_db_name = "task_outputs"
+default_db_name = "task_output"
 
 
 class TaskOutputSQLiteStorage:
@@ -31,7 +31,7 @@ class TaskOutputSQLiteStorage:
                 cursor = conn.cursor()
                 cursor.execute(
                     """
-                    CREATE TABLE IF NOT EXISTS task_outputs (
+                    CREATE TABLE IF NOT EXISTS task_output (
                         task_id TEXT PRIMARY KEY,
                         output JSON,
                         task_index INTEGER,
@@ -52,7 +52,7 @@ class TaskOutputSQLiteStorage:
             with sqlite3.connect(self.db_path) as conn:
                 cursor = conn.cursor()
                 cursor.execute(
-                        """INSERT OR REPLACE INTO task_outputs
+                        """INSERT OR REPLACE INTO task_output
                             (task_id, output, task_index, inputs, was_replayed, timestamp)
                             VALUES (?, ?, ?, ?, ?, ?)
                         """,
@@ -73,7 +73,7 @@ class TaskOutputSQLiteStorage:
                     fields.append(f"{k} = ?")
                     values.append(json.dumps(v) if isinstance(v, dict) else v)
 
-                query = f"UPDATE latest_kickoff_task_outputs SET {', '.join(fields)} WHERE task_index = ?"
+                query = f"UPDATE latest_kickoff_task_output SET {', '.join(fields)} WHERE task_index = ?"
                 values.append(task_index)
                 cursor.execute(query, tuple(values))
                 conn.commit()
@@ -93,7 +93,7 @@ class TaskOutputSQLiteStorage:
                 cursor = conn.cursor()
                 cursor.execute("""
                 SELECT *
-                FROM task_outputs
+                FROM task_output
                 ORDER BY task_index
                 """)
 
@@ -120,7 +120,7 @@ class TaskOutputSQLiteStorage:
         try:
             with sqlite3.connect(self.db_path) as conn:
                 cursor = conn.cursor()
-                cursor.execute("DELETE FROM task_outputs")
+                cursor.execute("DELETE FROM task_output")
                 conn.commit()
 
         except sqlite3.Error as e: