gnosisllm-knowledge 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

gnosisllm_knowledge/core/domain/document.py

@@ -26,17 +26,22 @@ class Document:
     This is the core domain object that flows through the knowledge pipeline.
     Documents are created by loaders, processed by chunkers, and stored by indexers.
 
+    Note:
+        This library is tenant-agnostic. Multi-tenancy is achieved through index
+        isolation (e.g., `knowledge-{account_id}`). Tenant information like account_id
+        should be passed in the metadata dictionary if needed for audit purposes.
+
     Attributes:
         content: The main text content of the document.
         source: Source identifier (URL, file path, etc.).
         doc_id: Unique identifier. Auto-generated from content hash if not provided.
         title: Optional document title.
         url: URL where the document was fetched from.
-        metadata: Arbitrary metadata dictionary.
+        metadata: Arbitrary metadata dictionary (can include tenant info for audit).
 
-        Multi-tenancy fields:
-            account_id: Account/tenant identifier.
+        Collection fields:
             collection_id: Collection the document belongs to.
+            collection_name: Collection name for display in aggregations.
             source_id: Source identifier within the collection.
 
         Chunking info:
@@ -70,9 +75,9 @@ class Document:
     url: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
-    # Multi-tenancy fields
-    account_id: str | None = None
+    # Collection fields
     collection_id: str | None = None
+    collection_name: str | None = None  # For display in aggregations
     source_id: str | None = None
 
     # Chunking info
@@ -138,8 +143,8 @@ class Document:
             title=self.title,
             url=self.url,
             metadata=self.metadata.copy(),
-            account_id=self.account_id,
             collection_id=self.collection_id,
+            collection_name=self.collection_name,
             source_id=self.source_id,
             chunk_index=chunk_index,
             total_chunks=total_chunks,
@@ -152,21 +157,21 @@ class Document:
             created_at=self.created_at,
         )
 
-    def with_tenant(
+    def with_collection(
         self,
-        account_id: str,
-        collection_id: str | None = None,
+        collection_id: str,
+        collection_name: str | None = None,
         source_id: str | None = None,
     ) -> Document:
-        """Create a new document with tenant information.
+        """Create a new document with collection information.
 
         Args:
-            account_id: Account/tenant identifier.
             collection_id: Collection identifier.
+            collection_name: Collection name for display.
             source_id: Source identifier.
 
         Returns:
-            New Document instance with tenant information set.
+            New Document instance with collection information set.
         """
         return Document(
             content=self.content,
@@ -175,8 +180,8 @@ class Document:
             title=self.title,
             url=self.url,
             metadata=self.metadata.copy(),
-            account_id=account_id,
-            collection_id=collection_id or self.collection_id,
+            collection_id=collection_id,
+            collection_name=collection_name or self.collection_name,
             source_id=source_id or self.source_id,
             chunk_index=self.chunk_index,
             total_chunks=self.total_chunks,
@@ -198,11 +203,6 @@ class Document:
         """Check if this document is a chunk of a larger document."""
         return self.chunk_index is not None and self.total_chunks is not None
 
-    @property
-    def is_multi_tenant(self) -> bool:
-        """Check if this document has tenant information."""
-        return self.account_id is not None
-
 
 @dataclass
 class TextChunk:

gnosisllm_knowledge/core/domain/memory.py

@@ -0,0 +1,440 @@
+"""Memory domain models for Agentic Memory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal
+
+
+class MemoryStrategy(str, Enum):
+    """Memory extraction strategies.
+
+    Attributes:
+        SEMANTIC: General facts and knowledge extraction.
+        USER_PREFERENCE: User preferences and choices.
+        SUMMARY: Conversation summaries.
+    """
+
+    SEMANTIC = "SEMANTIC"
+    USER_PREFERENCE = "USER_PREFERENCE"
+    SUMMARY = "SUMMARY"
+
+
+class MemoryType(str, Enum):
+    """Memory storage types.
+
+    Attributes:
+        WORKING: Raw conversation messages (short-term).
+        LONG_TERM: Extracted facts with embeddings.
+        SESSIONS: Session metadata.
+        HISTORY: Audit trail of operations.
+    """
+
+    WORKING = "working"
+    LONG_TERM = "long-term"
+    SESSIONS = "sessions"
+    HISTORY = "history"
+
+
+class PayloadType(str, Enum):
+    """Memory payload types.
+
+    Attributes:
+        CONVERSATIONAL: Conversation messages.
+        DATA: Structured data (agent state, traces).
+    """
+
+    CONVERSATIONAL = "conversational"
+    DATA = "data"
+
+
+class EmbeddingModelType(str, Enum):
+    """Embedding model types supported by OpenSearch.
+
+    Attributes:
+        TEXT_EMBEDDING: Dense vector embeddings (default).
+        SPARSE_ENCODING: Sparse vector encoding.
+    """
+
+    TEXT_EMBEDDING = "TEXT_EMBEDDING"
+    SPARSE_ENCODING = "SPARSE_ENCODING"
+
+
+class HistoryAction(str, Enum):
+    """History audit trail action types.
+
+    Attributes:
+        ADD: Memory was added.
+        UPDATE: Memory was updated.
+        DELETE: Memory was deleted.
+    """
+
+    ADD = "ADD"
+    UPDATE = "UPDATE"
+    DELETE = "DELETE"
+
+
+@dataclass
+class StrategyConfig:
+    """Configuration for a memory extraction strategy.
+
+    Each strategy MUST be scoped to namespace fields.
+    When storing memory, only strategies whose namespace fields are
+    present in the request will run.
+
+    Attributes:
+        type: Strategy type (SEMANTIC, USER_PREFERENCE, SUMMARY).
+        namespace: Fields used to scope this strategy (REQUIRED).
+        llm_result_path: JSONPath to extract LLM response.
+        system_prompt: Optional custom system prompt.
+        llm_id: Optional strategy-specific LLM override.
+    """
+
+    type: MemoryStrategy
+    namespace: list[str]  # REQUIRED - no default
+    llm_result_path: str | None = None
+    system_prompt: str | None = None
+    llm_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to OpenSearch API format."""
+        config: dict[str, Any] = {}
+        if self.llm_result_path:
+            config["llm_result_path"] = self.llm_result_path
+        if self.system_prompt:
+            config["system_prompt"] = self.system_prompt
+        if self.llm_id:
+            config["llm_id"] = self.llm_id
+
+        return {
+            "type": self.type.value,
+            "namespace": self.namespace,
+            "configuration": config,
+        }
+
+
+@dataclass
+class IndexSettings:
+    """Index-level settings for memory container indexes.
+
+    Attributes:
+        number_of_shards: Number of shards for the index.
+        number_of_replicas: Number of replicas for the index.
+    """
+
+    number_of_shards: int = 1
+    number_of_replicas: int = 1
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to OpenSearch index settings format."""
+        return {
+            "index": {
+                "number_of_shards": str(self.number_of_shards),
+                "number_of_replicas": str(self.number_of_replicas),
+            }
+        }
+
+
+@dataclass
+class ContainerIndexSettings:
+    """Settings for all memory container indexes.
+
+    Attributes:
+        session_index: Settings for session index.
+        short_term_memory_index: Settings for working memory index.
+        long_term_memory_index: Settings for long-term memory index.
+        long_term_memory_history_index: Settings for history index.
+    """
+
+    session_index: IndexSettings | None = None
+    short_term_memory_index: IndexSettings | None = None
+    long_term_memory_index: IndexSettings | None = None
+    long_term_memory_history_index: IndexSettings | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to OpenSearch API format."""
+        result: dict[str, Any] = {}
+        if self.session_index:
+            result["session_index"] = self.session_index.to_dict()
+        if self.short_term_memory_index:
+            result["short_term_memory_index"] = self.short_term_memory_index.to_dict()
+        if self.long_term_memory_index:
+            result["long_term_memory_index"] = self.long_term_memory_index.to_dict()
+        if self.long_term_memory_history_index:
+            result["long_term_memory_history_index"] = (
+                self.long_term_memory_history_index.to_dict()
+            )
+        return result
+
+
+@dataclass
+class ContainerConfig:
+    """Memory container configuration.
+
+    Attributes:
+        name: Container name.
+        description: Optional description.
+        strategies: List of extraction strategies.
+        embedding_model_id: OpenSearch embedding model ID.
+        embedding_model_type: Type of embedding model (TEXT_EMBEDDING or SPARSE_ENCODING).
+        llm_model_id: OpenSearch LLM model ID for inference.
+        llm_result_path: JSONPath to extract LLM response.
+        embedding_dimension: Embedding vector dimension.
+        index_prefix: Custom index prefix (optional).
+        use_system_index: Whether to use system indexes (default: True).
+        index_settings: Optional index-level settings (shards, replicas).
+    """
+
+    name: str
+    description: str | None = None
+    strategies: list[StrategyConfig] = field(default_factory=list)
+    embedding_model_id: str | None = None
+    embedding_model_type: EmbeddingModelType = EmbeddingModelType.TEXT_EMBEDDING
+    llm_model_id: str | None = None
+    llm_result_path: str = "$.choices[0].message.content"
+    embedding_dimension: int = 1536
+    index_prefix: str | None = None
+    use_system_index: bool = True
+    index_settings: ContainerIndexSettings | None = None
+
+
+@dataclass
+class ContainerInfo:
+    """Memory container information.
+
+    Attributes:
+        id: Container ID.
+        name: Container name.
+        description: Container description.
+        strategies: Configured strategies.
+        embedding_model_id: Embedding model ID.
+        llm_model_id: LLM model ID.
+        created_at: Creation timestamp.
+        updated_at: Last update timestamp.
+    """
+
+    id: str
+    name: str
+    description: str | None = None
+    strategies: list[MemoryStrategy] = field(default_factory=list)
+    embedding_model_id: str | None = None
+    llm_model_id: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass
+class Message:
+    """A conversation message.
+
+    Attributes:
+        role: Message role (user, assistant, system).
+        content: Message content.
+        timestamp: Optional timestamp.
+    """
+
+    role: Literal["user", "assistant", "system"]
+    content: str
+    timestamp: datetime | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to OpenSearch API format."""
+        return {
+            "role": self.role,
+            "content": [{"text": self.content, "type": "text"}],
+        }
+
+
+@dataclass
+class Namespace:
+    """Memory namespace for partitioning and strategy scoping.
+
+    Completely configurable key-value pairs for memory isolation.
+    Common fields: user_id, session_id, agent_id, org_id.
+
+    When creating a container, strategies are scoped to namespace fields.
+    When adding memory with `infer=True`, OpenSearch automatically runs
+    strategies based on which namespace fields are present.
+
+    Attributes:
+        values: Namespace key-value pairs.
+    """
+
+    values: dict[str, str] = field(default_factory=dict)
+
+    def __getitem__(self, key: str) -> str | None:
+        """Get namespace value by key."""
+        return self.values.get(key)
+
+    def __setitem__(self, key: str, value: str) -> None:
+        """Set namespace value by key."""
+        self.values[key] = value
+
+    def to_dict(self) -> dict[str, str]:
+        """Get namespace as dictionary for API calls."""
+        return dict(self.values)
+
+
+@dataclass
+class StoreRequest:
+    """Request to store memory.
+
+    Attributes:
+        messages: Conversation messages (for conversational payload).
+        structured_data: Structured data (for data payload).
+        namespace: Namespace for partitioning and strategy scoping.
+        payload_type: Type of payload.
+        infer: Whether to apply LLM inference for fact extraction.
+        metadata: Optional custom metadata.
+        tags: Optional custom tags.
+    """
+
+    messages: list[Message] | None = None
+    structured_data: dict[str, Any] | None = None
+    namespace: Namespace = field(default_factory=Namespace)
+    payload_type: PayloadType = PayloadType.CONVERSATIONAL
+    infer: bool = True
+    metadata: dict[str, Any] = field(default_factory=dict)
+    tags: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class StoreResult:
+    """Result of a store operation.
+
+    Attributes:
+        session_id: Session ID (for conversational).
+        working_memory_id: Working memory document ID.
+        long_term_count: Number of facts extracted (if infer=True).
+        extraction_time_ms: Time taken for extraction.
+    """
+
+    session_id: str | None = None
+    working_memory_id: str | None = None
+    long_term_count: int = 0
+    extraction_time_ms: int | None = None
+
+
+@dataclass
+class MemoryEntry:
+    """A memory entry from long-term storage.
+
+    Attributes:
+        id: Memory document ID.
+        content: The memory content (extracted fact).
+        strategy: Which strategy extracted this.
+        score: Similarity score (for search results).
+        namespace: Namespace values.
+        created_at: Creation timestamp.
+        metadata: Custom metadata.
+    """
+
+    id: str
+    content: str
+    strategy: MemoryStrategy | None = None
+    score: float = 0.0
+    namespace: dict[str, str] = field(default_factory=dict)
+    created_at: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RecallResult:
+    """Result of a recall (search) operation.
+
+    Attributes:
+        items: List of memory entries.
+        total: Total number of matches.
+        query: The search query.
+        took_ms: Time taken in milliseconds.
+    """
+
+    items: list[MemoryEntry]
+    total: int
+    query: str
+    took_ms: int = 0
+
+
+@dataclass
+class SessionInfo:
+    """Session information.
+
+    Attributes:
+        id: Session ID.
+        container_id: Parent container ID.
+        summary: Session summary text.
+        namespace: Session namespace.
+        started_at: Session start time.
+        ended_at: Session end time (if ended).
+        message_count: Number of messages in session.
+        messages: Session messages (if requested).
+        metadata: Custom session metadata.
+    """
+
+    id: str
+    container_id: str
+    summary: str | None = None
+    namespace: dict[str, str] = field(default_factory=dict)
+    started_at: datetime | None = None
+    ended_at: datetime | None = None
+    message_count: int = 0
+    messages: list[Message] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HistoryEntry:
+    """Audit trail entry for memory operations. READ-ONLY.
+
+    History is READ-ONLY and cannot be updated or deleted.
+
+    Attributes:
+        id: History entry ID.
+        memory_id: ID of the affected memory.
+        container_id: Parent container ID.
+        action: Operation type (ADD, UPDATE, DELETE).
+        owner_id: User who performed the action.
+        before: State before change (for UPDATE/DELETE).
+        after: State after change.
+        namespace: Namespace at time of operation.
+        tags: Tags at time of operation.
+        created_at: Operation timestamp.
+    """
+
+    id: str
+    memory_id: str
+    container_id: str
+    action: HistoryAction
+    owner_id: str | None = None
+    before: dict[str, Any] | None = None
+    after: dict[str, Any] | None = None
+    namespace: dict[str, str] = field(default_factory=dict)
+    tags: dict[str, str] = field(default_factory=dict)
+    created_at: datetime | None = None
+
+
+@dataclass
+class MemoryStats:
+    """Memory usage statistics.
+
+    Attributes:
+        container_id: Container ID.
+        container_name: Container name.
+        working_memory_count: Messages in working memory.
+        long_term_memory_count: Facts in long-term memory.
+        session_count: Number of sessions.
+        strategies_breakdown: Count per strategy.
+        storage_size_bytes: Estimated storage size.
+        last_updated: Last update timestamp.
+    """
+
+    container_id: str
+    container_name: str
+    working_memory_count: int = 0
+    long_term_memory_count: int = 0
+    session_count: int = 0
+    strategies_breakdown: dict[MemoryStrategy, int] = field(default_factory=dict)
+    storage_size_bytes: int = 0
+    last_updated: datetime | None = None

gnosisllm_knowledge/core/domain/result.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gnosisllm_knowledge.core.domain.document import Document
 
 
 @dataclass
@@ -13,7 +16,7 @@ class LoadResult:
     Attributes:
         source: The source that was loaded (URL, file path, etc.).
         source_type: Type of source (website, sitemap, file, etc.).
-        document_count: Number of documents loaded.
+        documents: List of loaded documents.
         success: Whether the operation succeeded.
         error_message: Error message if operation failed.
         duration_ms: Duration of the operation in milliseconds.
@@ -25,8 +28,8 @@ class LoadResult:
 
     source: str
     source_type: str
-    document_count: int
     success: bool
+    documents: list[Document] = field(default_factory=list)
     error_message: str | None = None
     duration_ms: float = 0.0
     metadata: dict[str, Any] = field(default_factory=dict)
@@ -34,6 +37,11 @@ class LoadResult:
     urls_failed: int = 0
     bytes_loaded: int = 0
 
+    @property
+    def document_count(self) -> int:
+        """Return the number of loaded documents."""
+        return len(self.documents)
+
     @property
     def success_rate(self) -> float:
         """Calculate the success rate for multi-URL loads."""

gnosisllm_knowledge/core/domain/search.py

@@ -39,6 +39,11 @@ class AgentType(str, Enum):
 class SearchQuery:
     """Search query with filters and options.
 
+    Note:
+        This library is tenant-agnostic. Multi-tenancy is achieved through index
+        isolation (e.g., `knowledge-{account_id}`). Callers should ensure they're
+        searching the correct tenant-specific index.
+
     Attributes:
         text: The search query text.
         mode: Search mode to use.
@@ -49,7 +54,6 @@ class SearchQuery:
         Filters:
             collection_ids: Filter by collection IDs.
             source_ids: Filter by source IDs.
-            account_id: Multi-tenant account filter.
             metadata_filters: Custom metadata filters.
 
         Advanced options:
@@ -69,7 +73,6 @@ class SearchQuery:
     # Filters
     collection_ids: list[str] | None = None
     source_ids: list[str] | None = None
-    account_id: str | None = None
     metadata_filters: dict[str, Any] = field(default_factory=dict)
 
     # Advanced options
@@ -89,26 +92,6 @@ class SearchQuery:
             min_score=self.min_score,
             collection_ids=self.collection_ids,
             source_ids=self.source_ids,
-            account_id=self.account_id,
-            metadata_filters=self.metadata_filters.copy(),
-            field_boosts=self.field_boosts.copy() if self.field_boosts else None,
-            include_highlights=self.include_highlights,
-            include_fields=self.include_fields,
-            exclude_fields=self.exclude_fields,
-            explain=self.explain,
-        )
-
-    def with_tenant(self, account_id: str) -> SearchQuery:
-        """Create a copy with tenant information."""
-        return SearchQuery(
-            text=self.text,
-            mode=self.mode,
-            limit=self.limit,
-            offset=self.offset,
-            min_score=self.min_score,
-            collection_ids=self.collection_ids,
-            source_ids=self.source_ids,
-            account_id=account_id,
             metadata_filters=self.metadata_filters.copy(),
             field_boosts=self.field_boosts.copy() if self.field_boosts else None,
             include_highlights=self.include_highlights,
@@ -216,13 +199,17 @@ class ReasoningStep:
 class AgenticSearchQuery:
     """Query for agentic search with conversation support.
 
+    Note:
+        This library is tenant-agnostic. Multi-tenancy is achieved through index
+        isolation (e.g., `knowledge-{account_id}`). Callers should ensure they're
+        searching the correct tenant-specific index.
+
     Attributes:
         text: The search query text.
         agent_type: Type of agent to use.
         conversation_id: ID for continuing a conversation.
         collection_ids: Filter by collection IDs.
         source_ids: Filter by source IDs.
-        account_id: Multi-tenant account filter.
         limit: Maximum number of source documents to retrieve.
         include_reasoning: Whether to include reasoning steps.
         metadata_filters: Custom metadata filters.
@@ -235,7 +222,6 @@ class AgenticSearchQuery:
     conversation_id: str | None = None
     collection_ids: list[str] | None = None
     source_ids: list[str] | None = None
-    account_id: str | None = None
     limit: int = 10
     include_reasoning: bool = True
     metadata_filters: dict[str, Any] = field(default_factory=dict)
@@ -250,7 +236,6 @@ class AgenticSearchQuery:
             limit=self.limit,
             collection_ids=self.collection_ids,
             source_ids=self.source_ids,
-            account_id=self.account_id,
             metadata_filters=self.metadata_filters.copy(),
         )
 
@@ -276,6 +261,7 @@ class AgenticSearchResult:
         total_tokens: Total tokens consumed.
         prompt_tokens: Tokens used in prompts.
         completion_tokens: Tokens used in completions.
+        generated_query: The DSL query generated by QueryPlanningTool (if applicable).
     """
 
     query: str
@@ -292,6 +278,7 @@ class AgenticSearchResult:
     total_tokens: int = 0
     prompt_tokens: int = 0
     completion_tokens: int = 0
+    generated_query: str | None = None  # DSL generated by QueryPlanningTool
 
     @property
     def has_answer(self) -> bool: