furthwe work on schema and typing

src/firedust/_utils/checks.py

@@ -0,0 +1,19 @@
+def is_unix_timestamp(timestamp: int | float) -> bool:
+    """
+    Check if the provided integer is a valid UNIX timestamp.
+
+    UNIX timestamps are typically in the range from 0 to 2**31 - 1,
+    covering dates from 1970-01-01 to 2038-01-19.
+
+    Source: https://www.unixtimestamp.com/
+
+    Args:
+        timestamp (int): The integer to check.
+
+    Returns:
+        bool: True if the integer is a valid UNIX timestamp, False otherwise.
+    """
+
+    MIN_UNIX_TIMESTAMP = 0  # 1 January 1970
+    MAX_UNIX_TIMESTAMP = 2**31 - 1  # 19 January 2038 for a 32-bit signed integer
+    return MIN_UNIX_TIMESTAMP <= timestamp <= MAX_UNIX_TIMESTAMP

src/firedust/_utils/types/_base.py

@@ -3,6 +3,8 @@
 
 from pydantic import BaseModel
 
+UNIX_TIMESTAMP = int | float
+
 
 class BaseConfig(BaseModel):
     """

src/firedust/_utils/types/assistant.py

@@ -1,7 +1,9 @@
-from typing import Any, List
+from typing import Any, List, Literal
 from uuid import UUID, uuid4
 
-from ._base import BaseConfig
+from pydantic import BaseModel
+
+from ._base import UNIX_TIMESTAMP, BaseConfig
 from .ability import AbilityConfig
 from .inference import InferenceConfig
 from .interface import Interfaces
@@ -41,3 +43,20 @@ def __setattr__(self, key: str, value: Any) -> None:
             )
 
         return super().__setattr__(key, value)
+
+
+class Message(BaseModel):
+    """
+    Represents a message between the user and the assistant.
+
+    Args:
+        user_id (UUID, optional): The unique identifier of the user. Defaults to None.
+        author (Literal["user", "assistant"]): The author of the message.
+        text (str): The text of the message.
+        timestamp (UNIX_TIMESTAMP, optional): The timestamp of the message. Defaults to None.
+    """
+
+    user_id: UUID | None = None
+    author: Literal["user", "assistant"]
+    text: str
+    timestamp: UNIX_TIMESTAMP | None = None

src/firedust/_utils/types/interface.py

@@ -13,6 +13,9 @@ class InterfaceConfig(BaseConfig):
     name: Literal["slack", "github", "discord", "email", "whatsapp"]
 
 
+# TODO: Finalize interface configurations.
+
+
 class SlackConfig(InterfaceConfig):
     """
     Configuration for Slack InterfaceConfig.

src/firedust/_utils/types/memory.py

@@ -3,55 +3,56 @@
 
 from pydantic import BaseModel, field_validator
 
-from ._base import BaseConfig
+from firedust._utils import checks
 
-MEMORY_ID = UUID
-MEMORY_COLLECTION_ID = UUID
-
-
-class MemorySource(BaseModel):
-    """
-    Represents a source of memories.
-    """
-
-    name: str
-    type: Literal["text", "image", "audio", "video"] = "text"
-    url: str | None = None
+from ._base import UNIX_TIMESTAMP, BaseConfig
 
 
 class MemoryItem(BaseConfig):
     """
-    A memory used by the assistant. The assistant recalls the title and
-    the context to answer questions and perform tasks.
+    A memory used by the AI assistant. The assistant recalls memories and their
+    context to answer questions and perform tasks.
+
+    Args:
+        collection (UUID): The collection that contains the memory.
+        context (str): The context of the memory.
+        embedding (List[float]): The embedding of the memory.
+        timestamp (UNIX_TIMESTAMP): The time when the memory was created.
+        type (Literal["text", "image", "audio", "video"]): The type of the memory. Defaults to "text".
+        source (str, optional): The source of the memory. Defaults to None.
     """
 
-    id: MEMORY_ID = uuid4()
-    title: str
+    collection: UUID
     context: str
-    tags: List[str] | None = None
-    embedding: List[float] | None = None
-    source: MemorySource | None = None
+    embedding: List[float]
+    timestamp: UNIX_TIMESTAMP
+    type: Literal["text", "image", "audio", "video"] = "text"
+    source: str | None = None
 
     @field_validator("context")
     def validate_context_length(cls, context: str) -> str | Exception:
         if len(context) > 2000:
             raise ValueError("Memory context exceeds maximum length of 2000 characters")
         return context
 
-    @field_validator("title")
-    def validate_title_length(cls, title: str) -> str | Exception:
-        if len(title) > 140:
-            raise ValueError("Title exceeds maximum length of 140 characters")
-        return title
+    @field_validator("timestamp")
+    def validate_timestamp(
+        cls, timestamp: UNIX_TIMESTAMP
+    ) -> UNIX_TIMESTAMP | Exception:
+        # Check that the timestamp is UNIX format
+        try:
+            checks.is_unix_timestamp(timestamp)
+        except ValueError as e:
+            raise ValueError(f"Invalid timestamp: {e}")
+        return timestamp
 
 
 class MemoriesCollectionItem(BaseConfig):
     """
     Represents a collection of memories used by the assistant.
     """
 
-    id: MEMORY_COLLECTION_ID = uuid4()
-    collection: List[MEMORY_ID] | None = None
+    collection: List[UUID] | None = None
 
 
 class MemoryConfig(BaseModel):
@@ -62,8 +63,8 @@ class MemoryConfig(BaseModel):
     embedding_model: Literal[
         "sand/MiniLM-L6-v2", "sand/UAE-Large-v1"
     ] = "sand/MiniLM-L6-v2"
-    default_collection: MEMORY_COLLECTION_ID = uuid4()
-    extra_collections: List[MEMORY_COLLECTION_ID] = []
+    default_collection: UUID = uuid4()
+    extra_collections: List[UUID] = []
 
     def __setattr__(self, key: str, value: Any) -> None:
         # set immutable attributes

src/firedust/assistant.py

@@ -36,7 +36,7 @@
 import logging
 import os
 from typing import List
-from uuid import UUID
+from uuid import UUID, uuid4
 
 from firedust._utils.api import APIClient
 from firedust._utils.errors import AssistantError

src/firedust/learning/_base.py

@@ -27,7 +27,8 @@ def fast(self, text: str) -> None:
         """
         The fastest way to teach the assistant is by providing data in
         string format. This can be documentation, code, examples, or any
-        other data that you want the assistant to learn from.
+        other data. The assistant will learn the information and use it
+        to answer questions and perform tasks.
 
         Args:
             text (str): The text to learn.

src/firedust/memory/_base.py

@@ -28,11 +28,12 @@
 """
 
 from typing import List
+from uuid import UUID
 
 from firedust._utils.api import APIClient
 from firedust._utils.errors import MemoryError
 from firedust._utils.types.assistant import AssistantConfig
-from firedust._utils.types.memory import MEMORY_COLLECTION_ID, MEMORY_ID, MemoryItem
+from firedust._utils.types.memory import MemoryItem
 
 
 class Memory:
@@ -81,20 +82,18 @@ def add(self, memory: MemoryItem) -> None:
             data={"memory": memory.model_dump_json()},
         )
 
-    def remove(self, memory_id: MEMORY_ID) -> None:
+    def remove(self, memory_id: UUID) -> None:
         """
         Removes a memory from the assistant's default memory collection.
 
         Args:
-            memory_id (MEMORY_ID): The ID of the memory item to remove.
+            memory_id (UUID): The ID of the memory item to remove.
         """
         self.api_client.delete(
             f"assistant/{self.config.id}/memory/remove/{memory_id}",
         )
 
-    def list(
-        self, collection_id: MEMORY_COLLECTION_ID | None = None
-    ) -> List[MEMORY_ID]:
+    def list(self, collection_id: UUID | None = None) -> List[UUID]:
         """
         List all memory items in a given collection id. If no collection id is provided,
         the default collection is used.
@@ -108,7 +107,7 @@ def list(
         )
 
         if response["status_code"] == 200:
-            memory_ids: List[MEMORY_ID] = response["collection"]
+            memory_ids: List[UUID] = response["collection"]
             return memory_ids
         elif response["status_code"] == 401:
             raise MemoryError("Memory collection not found.")
@@ -149,7 +148,7 @@ def __init__(self, config: AssistantConfig, api_client: APIClient) -> None:
         self.config = config
         self.api_client = api_client
 
-    def attach(self, id: MEMORY_COLLECTION_ID) -> None:
+    def attach(self, id: UUID) -> None:
         """
         Attaches an existing memory collection to the assistant.
         """
@@ -167,7 +166,7 @@ def attach(self, id: MEMORY_COLLECTION_ID) -> None:
         else:
             raise MemoryError(f"Unknown response: {response}")
 
-    def detach(self, id: MEMORY_COLLECTION_ID) -> None:
+    def detach(self, id: UUID) -> None:
         """
         Detaches an existing memory collection from the assistant.
         """
@@ -187,7 +186,7 @@ def detach(self, id: MEMORY_COLLECTION_ID) -> None:
         else:
             raise MemoryError(f"Unknown response: {response}")
 
-    def list(self) -> List[MEMORY_COLLECTION_ID]:
+    def list(self) -> List[UUID]:
         """
         List all memory collections attached to the assistant.
         """

tests/_utils/test_checks.py

@@ -0,0 +1,14 @@
+from firedust._utils.checks import is_unix_timestamp
+
+
+def test_is_unix_timestamp() -> None:
+    # Test valid unix timestamp
+    assert is_unix_timestamp(1625097600) is True
+    assert is_unix_timestamp(1625097600.5) is True
+    assert is_unix_timestamp(0) is True
+
+    # Before 1970
+    assert is_unix_timestamp(-1) is False
+
+    # After 2038
+    assert is_unix_timestamp(2**31) is False