sf-vector-sdk 0.2.0__py3-none-any.whl

vector_sdk/generated/embedding_pipeline/query/v1/query_pb2.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: embedding_pipeline/query/v1/query.proto
+# Protobuf Python Version: 6.33.4
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    4,
+    '',
+    'embedding_pipeline/query/v1/query.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from embedding_pipeline.content_types.v1 import content_types_pb2 as embedding__pipeline_dot_content__types_dot_v1_dot_content__types__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\'embedding_pipeline/query/v1/query.proto\x12\x1b\x65mbedding_pipeline.query.v1\x1a\x37\x65mbedding_pipeline/content_types/v1/content_types.proto\"\xc7\x04\n\x0cQueryRequest\x12\x1d\n\nrequest_id\x18\x01 \x01(\tR\trequestId\x12\x1d\n\nquery_text\x18\x02 \x01(\tR\tqueryText\x12O\n\x08\x64\x61tabase\x18\x03 \x01(\x0e\x32\x33.embedding_pipeline.content_types.v1.VectorDatabaseR\x08\x64\x61tabase\x12_\n\x10\x65mbedding_config\x18\x04 \x01(\x0b\x32\x34.embedding_pipeline.content_types.v1.EmbeddingConfigR\x0f\x65mbeddingConfig\x12K\n\x0cquery_config\x18\x05 \x01(\x0b\x32(.embedding_pipeline.query.v1.QueryConfigR\x0bqueryConfig\x12I\n\x08priority\x18\x06 \x01(\x0e\x32-.embedding_pipeline.content_types.v1.PriorityR\x08priority\x12S\n\x08metadata\x18\x07 \x03(\x0b\x32\x37.embedding_pipeline.query.v1.QueryRequest.MetadataEntryR\x08metadata\x12\x1d\n\ncreated_at\x18\x08 \x01(\tR\tcreatedAt\x1a;\n\rMetadataEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\tR\x05value:\x02\x38\x01\"\xfa\x02\n\x0bQueryConfig\x12\x13\n\x05top_k\x18\x01 \x01(\x05R\x04topK\x12\x1b\n\tmin_score\x18\x02 \x01(\x02R\x08minScore\x12O\n\x07\x66ilters\x18\x03 \x03(\x0b\x32\x35.embedding_pipeline.query.v1.QueryConfig.FiltersEntryR\x07\x66ilters\x12\x1c\n\tnamespace\x18\x04 \x01(\tR\tnamespace\x12\x1e\n\ncollection\x18\x05 \x01(\tR\ncollection\x12\x1a\n\x08\x64\x61tabase\x18\x06 \x01(\tR\x08\x64\x61tabase\x12\'\n\x0finclude_vectors\x18\x07 \x01(\x08R\x0eincludeVectors\x12)\n\x10include_metadata\x18\x08 \x01(\x08R\x0fincludeMetadata\x1a:\n\x0c\x46iltersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\tR\x05value:\x02\x38\x01\"\x83\x02\n\x0bQueryResult\x12\x1d\n\nrequest_id\x18\x01 \x01(\tR\trequestId\x12\x16\n\x06status\x18\x02 \x01(\tR\x06status\x12\x42\n\x07matches\x18\x03 \x03(\x0b\x32(.embedding_pipeline.query.v1.VectorMatchR\x07matches\x12\x14\n\x05\x65rror\x18\x04 \x01(\tR\x05\x65rror\x12@\n\x06timing\x18\x05 \x01(\x0b\x32(.embedding_pipeline.query.v1.QueryTimingR\x06timing\x12!\n\x0c\x63ompleted_at\x18\x06 \x01(\tR\x0b\x63ompletedAt\"\xdc\x01\n\x0bVectorMatch\x12\x0e\n\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n\x05score\x18\x02 \x01(\x02R\x05score\x12R\n\x08metadata\x18\x03 \x03(\x0b\x32\x36.embedding_pipeline.query.v1.VectorMatch.MetadataEntryR\x08metadata\x12\x16\n\x06vector\x18\x04 \x03(\x02R\x06vector\x1a;\n\rMetadataEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\tR\x05value:\x02\x38\x01\"\x8c\x01\n\x0bQueryTiming\x12\"\n\rqueue_wait_ms\x18\x01 \x01(\x03R\x0bqueueWaitMs\x12!\n\x0c\x65mbedding_ms\x18\x02 \x01(\x03R\x0b\x65mbeddingMs\x12\x1b\n\tsearch_ms\x18\x03 \x01(\x03R\x08searchMs\x12\x19\n\x08total_ms\x18\x04 \x01(\x03R\x07totalMsBgZegithub.com/GoStudyFetchGo/vector-management-monorepo/packages/go/proto-go/embedding_pipeline/query/v1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'embedding_pipeline.query.v1.query_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Zegithub.com/GoStudyFetchGo/vector-management-monorepo/packages/go/proto-go/embedding_pipeline/query/v1'
+  _globals['_QUERYREQUEST_METADATAENTRY']._loaded_options = None
+  _globals['_QUERYREQUEST_METADATAENTRY']._serialized_options = b'8\001'
+  _globals['_QUERYCONFIG_FILTERSENTRY']._loaded_options = None
+  _globals['_QUERYCONFIG_FILTERSENTRY']._serialized_options = b'8\001'
+  _globals['_VECTORMATCH_METADATAENTRY']._loaded_options = None
+  _globals['_VECTORMATCH_METADATAENTRY']._serialized_options = b'8\001'
+  _globals['_QUERYREQUEST']._serialized_start=130
+  _globals['_QUERYREQUEST']._serialized_end=713
+  _globals['_QUERYREQUEST_METADATAENTRY']._serialized_start=654
+  _globals['_QUERYREQUEST_METADATAENTRY']._serialized_end=713
+  _globals['_QUERYCONFIG']._serialized_start=716
+  _globals['_QUERYCONFIG']._serialized_end=1094
+  _globals['_QUERYCONFIG_FILTERSENTRY']._serialized_start=1036
+  _globals['_QUERYCONFIG_FILTERSENTRY']._serialized_end=1094
+  _globals['_QUERYRESULT']._serialized_start=1097
+  _globals['_QUERYRESULT']._serialized_end=1356
+  _globals['_VECTORMATCH']._serialized_start=1359
+  _globals['_VECTORMATCH']._serialized_end=1579
+  _globals['_VECTORMATCH_METADATAENTRY']._serialized_start=654
+  _globals['_VECTORMATCH_METADATAENTRY']._serialized_end=713
+  _globals['_QUERYTIMING']._serialized_start=1582
+  _globals['_QUERYTIMING']._serialized_end=1722
+# @@protoc_insertion_point(module_scope)

vector_sdk/generated/embedding_pipeline/query/v1/query_pb2.pyi

@@ -0,0 +1,109 @@
+from embedding_pipeline.content_types.v1 import content_types_pb2 as _content_types_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class QueryRequest(_message.Message):
+    __slots__ = ("request_id", "query_text", "database", "embedding_config", "query_config", "priority", "metadata", "created_at")
+    class MetadataEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: str
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+    REQUEST_ID_FIELD_NUMBER: _ClassVar[int]
+    QUERY_TEXT_FIELD_NUMBER: _ClassVar[int]
+    DATABASE_FIELD_NUMBER: _ClassVar[int]
+    EMBEDDING_CONFIG_FIELD_NUMBER: _ClassVar[int]
+    QUERY_CONFIG_FIELD_NUMBER: _ClassVar[int]
+    PRIORITY_FIELD_NUMBER: _ClassVar[int]
+    METADATA_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    request_id: str
+    query_text: str
+    database: _content_types_pb2.VectorDatabase
+    embedding_config: _content_types_pb2.EmbeddingConfig
+    query_config: QueryConfig
+    priority: _content_types_pb2.Priority
+    metadata: _containers.ScalarMap[str, str]
+    created_at: str
+    def __init__(self, request_id: _Optional[str] = ..., query_text: _Optional[str] = ..., database: _Optional[_Union[_content_types_pb2.VectorDatabase, str]] = ..., embedding_config: _Optional[_Union[_content_types_pb2.EmbeddingConfig, _Mapping]] = ..., query_config: _Optional[_Union[QueryConfig, _Mapping]] = ..., priority: _Optional[_Union[_content_types_pb2.Priority, str]] = ..., metadata: _Optional[_Mapping[str, str]] = ..., created_at: _Optional[str] = ...) -> None: ...
+
+class QueryConfig(_message.Message):
+    __slots__ = ("top_k", "min_score", "filters", "namespace", "collection", "database", "include_vectors", "include_metadata")
+    class FiltersEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: str
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+    TOP_K_FIELD_NUMBER: _ClassVar[int]
+    MIN_SCORE_FIELD_NUMBER: _ClassVar[int]
+    FILTERS_FIELD_NUMBER: _ClassVar[int]
+    NAMESPACE_FIELD_NUMBER: _ClassVar[int]
+    COLLECTION_FIELD_NUMBER: _ClassVar[int]
+    DATABASE_FIELD_NUMBER: _ClassVar[int]
+    INCLUDE_VECTORS_FIELD_NUMBER: _ClassVar[int]
+    INCLUDE_METADATA_FIELD_NUMBER: _ClassVar[int]
+    top_k: int
+    min_score: float
+    filters: _containers.ScalarMap[str, str]
+    namespace: str
+    collection: str
+    database: str
+    include_vectors: bool
+    include_metadata: bool
+    def __init__(self, top_k: _Optional[int] = ..., min_score: _Optional[float] = ..., filters: _Optional[_Mapping[str, str]] = ..., namespace: _Optional[str] = ..., collection: _Optional[str] = ..., database: _Optional[str] = ..., include_vectors: _Optional[bool] = ..., include_metadata: _Optional[bool] = ...) -> None: ...
+
+class QueryResult(_message.Message):
+    __slots__ = ("request_id", "status", "matches", "error", "timing", "completed_at")
+    REQUEST_ID_FIELD_NUMBER: _ClassVar[int]
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    MATCHES_FIELD_NUMBER: _ClassVar[int]
+    ERROR_FIELD_NUMBER: _ClassVar[int]
+    TIMING_FIELD_NUMBER: _ClassVar[int]
+    COMPLETED_AT_FIELD_NUMBER: _ClassVar[int]
+    request_id: str
+    status: str
+    matches: _containers.RepeatedCompositeFieldContainer[VectorMatch]
+    error: str
+    timing: QueryTiming
+    completed_at: str
+    def __init__(self, request_id: _Optional[str] = ..., status: _Optional[str] = ..., matches: _Optional[_Iterable[_Union[VectorMatch, _Mapping]]] = ..., error: _Optional[str] = ..., timing: _Optional[_Union[QueryTiming, _Mapping]] = ..., completed_at: _Optional[str] = ...) -> None: ...
+
+class VectorMatch(_message.Message):
+    __slots__ = ("id", "score", "metadata", "vector")
+    class MetadataEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: str
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+    ID_FIELD_NUMBER: _ClassVar[int]
+    SCORE_FIELD_NUMBER: _ClassVar[int]
+    METADATA_FIELD_NUMBER: _ClassVar[int]
+    VECTOR_FIELD_NUMBER: _ClassVar[int]
+    id: str
+    score: float
+    metadata: _containers.ScalarMap[str, str]
+    vector: _containers.RepeatedScalarFieldContainer[float]
+    def __init__(self, id: _Optional[str] = ..., score: _Optional[float] = ..., metadata: _Optional[_Mapping[str, str]] = ..., vector: _Optional[_Iterable[float]] = ...) -> None: ...
+
+class QueryTiming(_message.Message):
+    __slots__ = ("queue_wait_ms", "embedding_ms", "search_ms", "total_ms")
+    QUEUE_WAIT_MS_FIELD_NUMBER: _ClassVar[int]
+    EMBEDDING_MS_FIELD_NUMBER: _ClassVar[int]
+    SEARCH_MS_FIELD_NUMBER: _ClassVar[int]
+    TOTAL_MS_FIELD_NUMBER: _ClassVar[int]
+    queue_wait_ms: int
+    embedding_ms: int
+    search_ms: int
+    total_ms: int
+    def __init__(self, queue_wait_ms: _Optional[int] = ..., embedding_ms: _Optional[int] = ..., search_ms: _Optional[int] = ..., total_ms: _Optional[int] = ...) -> None: ...

vector_sdk/generated/embedding_pipeline/tools/v1/tools_pb2.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: embedding_pipeline/tools/v1/tools.proto
+# Protobuf Python Version: 6.33.4
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    4,
+    '',
+    'embedding_pipeline/tools/v1/tools.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\'embedding_pipeline/tools/v1/tools.proto\x12\x1b\x65mbedding_pipeline.tools.v1*\xc9\x01\n\x0eToolCollection\x12\x1f\n\x1bTOOL_COLLECTION_UNSPECIFIED\x10\x00\x12\x1d\n\x19TOOL_COLLECTION_FLASHCARD\x10\x01\x12!\n\x1dTOOL_COLLECTION_TEST_QUESTION\x10\x02\x12(\n$TOOL_COLLECTION_SPACED_TEST_QUESTION\x10\x03\x12*\n&TOOL_COLLECTION_AUDIO_RECAP_V2_SECTION\x10\x04*\xb2\x01\n\rFlashCardType\x12\x1f\n\x1b\x46LASH_CARD_TYPE_UNSPECIFIED\x10\x00\x12\x19\n\x15\x46LASH_CARD_TYPE_BASIC\x10\x01\x12\x19\n\x15\x46LASH_CARD_TYPE_CLOZE\x10\x02\x12%\n!FLASH_CARD_TYPE_FILL_IN_THE_BLANK\x10\x03\x12#\n\x1f\x46LASH_CARD_TYPE_MULTIPLE_CHOICE\x10\x04\x42gZegithub.com/GoStudyFetchGo/vector-management-monorepo/packages/go/proto-go/embedding_pipeline/tools/v1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'embedding_pipeline.tools.v1.tools_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Zegithub.com/GoStudyFetchGo/vector-management-monorepo/packages/go/proto-go/embedding_pipeline/tools/v1'
+  _globals['_TOOLCOLLECTION']._serialized_start=73
+  _globals['_TOOLCOLLECTION']._serialized_end=274
+  _globals['_FLASHCARDTYPE']._serialized_start=277
+  _globals['_FLASHCARDTYPE']._serialized_end=455
+# @@protoc_insertion_point(module_scope)

vector_sdk/generated/embedding_pipeline/tools/v1/tools_pb2.pyi

@@ -0,0 +1,31 @@
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class ToolCollection(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    TOOL_COLLECTION_UNSPECIFIED: _ClassVar[ToolCollection]
+    TOOL_COLLECTION_FLASHCARD: _ClassVar[ToolCollection]
+    TOOL_COLLECTION_TEST_QUESTION: _ClassVar[ToolCollection]
+    TOOL_COLLECTION_SPACED_TEST_QUESTION: _ClassVar[ToolCollection]
+    TOOL_COLLECTION_AUDIO_RECAP_V2_SECTION: _ClassVar[ToolCollection]
+
+class FlashCardType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    FLASH_CARD_TYPE_UNSPECIFIED: _ClassVar[FlashCardType]
+    FLASH_CARD_TYPE_BASIC: _ClassVar[FlashCardType]
+    FLASH_CARD_TYPE_CLOZE: _ClassVar[FlashCardType]
+    FLASH_CARD_TYPE_FILL_IN_THE_BLANK: _ClassVar[FlashCardType]
+    FLASH_CARD_TYPE_MULTIPLE_CHOICE: _ClassVar[FlashCardType]
+TOOL_COLLECTION_UNSPECIFIED: ToolCollection
+TOOL_COLLECTION_FLASHCARD: ToolCollection
+TOOL_COLLECTION_TEST_QUESTION: ToolCollection
+TOOL_COLLECTION_SPACED_TEST_QUESTION: ToolCollection
+TOOL_COLLECTION_AUDIO_RECAP_V2_SECTION: ToolCollection
+FLASH_CARD_TYPE_UNSPECIFIED: FlashCardType
+FLASH_CARD_TYPE_BASIC: FlashCardType
+FLASH_CARD_TYPE_CLOZE: FlashCardType
+FLASH_CARD_TYPE_FILL_IN_THE_BLANK: FlashCardType
+FLASH_CARD_TYPE_MULTIPLE_CHOICE: FlashCardType

vector_sdk/hash/__init__.py

@@ -0,0 +1,31 @@
+"""
+Content Hash Module.
+
+Generates deterministic content hashes for learning tools.
+Mirrors the TypeScript implementation in packages/ts/vector-sdk/src/common/hash.ts
+
+See docs/CONTENT-HASH-SPEC.md for the full specification.
+"""
+
+from .hasher import compute_content_hash, extract_tool_text
+from .types import (
+    AnswerObject,
+    AudioRecapSectionData,
+    FlashCardData,
+    FlashCardType,
+    MultipleChoiceOption,
+    QuestionData,
+    ToolCollection,
+)
+
+__all__ = [
+    "compute_content_hash",
+    "extract_tool_text",
+    "ToolCollection",
+    "FlashCardType",
+    "FlashCardData",
+    "QuestionData",
+    "AudioRecapSectionData",
+    "MultipleChoiceOption",
+    "AnswerObject",
+]

vector_sdk/hash/hasher.py

@@ -0,0 +1,259 @@
+"""
+Content hash computation.
+
+Generates deterministic content hashes for learning tools.
+Mirrors the TypeScript implementation in packages/ts/vector-sdk/src/common/hash.ts
+"""
+
+import hashlib
+import re
+from typing import Union
+
+from .types import (
+    AudioRecapSectionData,
+    FlashCardData,
+    MultipleChoiceOption,
+    QuestionData,
+    ToolCollection,
+)
+
+# Hash length in hex characters (128 bits = 32 hex chars)
+HASH_LENGTH = 32
+
+
+def compute_content_hash(
+    tool_collection: ToolCollection,
+    data: Union[FlashCardData, QuestionData, AudioRecapSectionData, dict],
+) -> str:
+    """
+    Compute a deterministic content hash for a learning tool.
+
+    The hash is computed by:
+    1. Extracting text content based on the tool collection type
+    2. Computing SHA-256 hash of the text
+    3. Truncating to first 32 hex characters (128 bits)
+
+    For FlashCard, if no type is provided, defaults to "BASIC".
+    Other tool collections (TestQuestion, SpacedTestQuestion, AudioRecapV2Section)
+    do not have type variants.
+
+    Args:
+        tool_collection: The tool type (FlashCard, TestQuestion, etc.)
+        data: Tool-specific data (can be Pydantic model or dict)
+
+    Returns:
+        The content hash (32 hex chars) or empty string if no content
+    """
+    text = extract_tool_text(tool_collection, data)
+    if not text:
+        return ""
+    return _compute_hash(text)
+
+
+def extract_tool_text(
+    tool_collection: ToolCollection,
+    data: Union[FlashCardData, QuestionData, AudioRecapSectionData, dict],
+) -> str:
+    """
+    Extract the text content from a learning tool for embedding.
+
+    This function extracts the text that will be used for vector embedding
+    based on the tool collection type. Use this when you need the raw text
+    for embedding rather than the hash.
+
+    Text extraction rules:
+    - FlashCard (BASIC): "Term: {term} Definition: {definition}"
+    - FlashCard (CLOZE/FILL_IN_THE_BLANK): Same as BASIC, with {{...}} syntax stripped
+    - FlashCard (MULTIPLE_CHOICE): "Term: {term} Options: {opt1, opt2, ...}"
+    - TestQuestion/SpacedTestQuestion: "Question: {question} Answers: {a1, a2, ...} Explanation: {explanation}"
+    - AudioRecapV2Section: "Script: {script}"
+
+    Args:
+        tool_collection: The tool type (FlashCard, TestQuestion, etc.)
+        data: Tool-specific data (can be Pydantic model or dict)
+
+    Returns:
+        The extracted text string or empty string if no content
+
+    Example:
+        >>> text = extract_tool_text(
+        ...     "FlashCard",
+        ...     {"type": "BASIC", "term": "Hello", "definition": "World"}
+        ... )
+        >>> # Returns: "Term: Hello Definition: World"
+    """
+    # Convert dict to appropriate model if needed
+    if isinstance(data, dict):
+        data_dict = data
+    else:
+        data_dict = data.model_dump(by_alias=True) if hasattr(data, "model_dump") else dict(data)
+
+    if tool_collection == "FlashCard":
+        return _extract_flashcard_text(data_dict)
+    elif tool_collection in ("TestQuestion", "SpacedTestQuestion"):
+        return _extract_question_text(data_dict)
+    elif tool_collection == "AudioRecapV2Section":
+        return _extract_audio_recap_text(data_dict)
+    else:
+        return ""
+
+
+def _compute_hash(text: str) -> str:
+    """Compute SHA-256 hash and truncate to HASH_LENGTH characters."""
+    if not text:
+        return ""
+    hash_bytes = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    return hash_bytes[:HASH_LENGTH]
+
+
+def _extract_flashcard_text(data: dict) -> str:
+    """
+    Extract text from a FlashCard document.
+
+    Handles all variants: BASIC, CLOZE, FILL_IN_THE_BLANK, MULTIPLE_CHOICE
+    """
+    parts: list[str] = []
+    card_type = data.get("type") or "BASIC"
+
+    # Extract term (all types have this)
+    term = data.get("term")
+    if term:
+        clean_term = _strip_flashcard_syntax(term.strip())
+        if clean_term:
+            parts.append(f"Term: {clean_term}")
+
+    # Handle definition/options based on type
+    if card_type == "MULTIPLE_CHOICE":
+        # Check both camelCase and snake_case keys
+        options = data.get("multipleChoiceOptions") or data.get("multiple_choice_options")
+        option_texts = _get_multiple_choice_options(options)
+        if option_texts:
+            parts.append(f"Options: {', '.join(option_texts)}")
+    else:
+        # BASIC, CLOZE, FILL_IN_THE_BLANK use definition
+        definition = data.get("definition")
+        if definition:
+            clean_def = _strip_flashcard_syntax(definition.strip())
+            if clean_def:
+                parts.append(f"Definition: {clean_def}")
+
+    return " ".join(parts)
+
+
+def _extract_question_text(data: dict) -> str:
+    """
+    Extract text from TestQuestion or SpacedTestQuestion.
+
+    Format: "Question: {question} Answers: {a1, a2, ...} Explanation: {explanation}"
+    """
+    parts: list[str] = []
+
+    question = data.get("question")
+    if question:
+        trimmed = question.strip()
+        if trimmed:
+            parts.append(f"Question: {trimmed}")
+
+    # Extract answers array
+    answers = data.get("answers")
+    answer_texts = _get_string_array(answers)
+    if answer_texts:
+        parts.append(f"Answers: {', '.join(answer_texts)}")
+
+    explanation = data.get("explanation")
+    if explanation:
+        trimmed = explanation.strip()
+        if trimmed:
+            parts.append(f"Explanation: {trimmed}")
+
+    return " ".join(parts)
+
+
+def _extract_audio_recap_text(data: dict) -> str:
+    """
+    Extract text from AudioRecapV2Section.
+
+    Format: "Script: {script}"
+    """
+    script = data.get("script")
+    if script:
+        trimmed = script.strip()
+        if trimmed:
+            return f"Script: {trimmed}"
+    return ""
+
+
+def _strip_flashcard_syntax(text: str) -> str:
+    """
+    Strip {{...}} markers from cloze/fill-in-blank text.
+
+    Example: "The {{mitochondria}} is the powerhouse" -> "The mitochondria is the powerhouse"
+    """
+    if not text:
+        return ""
+    # Replace {{word}} with just word
+    return re.sub(r"\{\{([^}]+)\}\}", r"\1", text)
+
+
+def _get_multiple_choice_options(options: list | None) -> list[str]:
+    """
+    Extract option text from multiple choice options array.
+
+    Options can be strings or objects with "text" or "option" fields.
+    """
+    if not options or not isinstance(options, list):
+        return []
+
+    result: list[str] = []
+    for opt in options:
+        text = _extract_option_text(opt)
+        if text:
+            result.append(text)
+    return result
+
+
+def _extract_option_text(item: str | dict | MultipleChoiceOption) -> str:
+    """Extract text from a single option (string or object)."""
+    if isinstance(item, str):
+        return item.strip()
+
+    if isinstance(item, dict):
+        # Try "text" field first, then "option"
+        text = item.get("text")
+        if text and isinstance(text, str):
+            return text.strip()
+        option = item.get("option")
+        if option and isinstance(option, str):
+            return option.strip()
+
+    if hasattr(item, "text") and item.text:
+        return item.text.strip()
+    if hasattr(item, "option") and item.option:
+        return item.option.strip()
+
+    return ""
+
+
+def _get_string_array(answers: list | None) -> list[str]:
+    """Extract string array from answers (handles both string[] and AnswerObject[])."""
+    if not answers or not isinstance(answers, list):
+        return []
+
+    result: list[str] = []
+    for ans in answers:
+        if isinstance(ans, str):
+            trimmed = ans.strip()
+            if trimmed:
+                result.append(trimmed)
+        elif isinstance(ans, dict):
+            text = ans.get("text")
+            if text and isinstance(text, str):
+                trimmed = text.strip()
+                if trimmed:
+                    result.append(trimmed)
+        elif hasattr(ans, "text") and ans.text:
+            trimmed = ans.text.strip()
+            if trimmed:
+                result.append(trimmed)
+
+    return result

vector_sdk/hash/types.py

@@ -0,0 +1,67 @@
+"""
+Type definitions for content hashing.
+
+These types mirror the TypeScript SDK types and are derived from the proto definitions.
+"""
+
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Tool collection types
+ToolCollection = Literal["FlashCard", "TestQuestion", "SpacedTestQuestion", "AudioRecapV2Section"]
+
+# FlashCard type variants
+FlashCardType = Literal["BASIC", "CLOZE", "FILL_IN_THE_BLANK", "MULTIPLE_CHOICE"]
+
+
+class MultipleChoiceOption(BaseModel):
+    """Multiple choice option structure."""
+
+    model_config = ConfigDict(extra="allow")
+
+    text: Optional[str] = None
+    option: Optional[str] = None
+
+
+class AnswerObject(BaseModel):
+    """Answer object structure (can be string or object with text field)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    text: Optional[str] = None
+
+
+class FlashCardData(BaseModel):
+    """
+    FlashCard data for content hashing.
+
+    If type is not provided, defaults to "BASIC".
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: Optional[FlashCardType] = "BASIC"
+    term: Optional[str] = None
+    definition: Optional[str] = None
+    multiple_choice_options: Optional[list[Union[str, MultipleChoiceOption, dict]]] = Field(
+        default=None, alias="multipleChoiceOptions"
+    )
+
+
+class QuestionData(BaseModel):
+    """Question data for TestQuestion and SpacedTestQuestion."""
+
+    model_config = ConfigDict(extra="allow")
+
+    question: Optional[str] = None
+    answers: Optional[list[Union[str, AnswerObject, dict]]] = None
+    explanation: Optional[str] = None
+
+
+class AudioRecapSectionData(BaseModel):
+    """AudioRecapV2Section data for content hashing."""
+
+    model_config = ConfigDict(extra="allow")
+
+    script: Optional[str] = None

vector_sdk/namespaces/__init__.py

@@ -0,0 +1,13 @@
+"""Namespace exports for the Vector SDK."""
+
+from vector_sdk.namespaces.base import BaseNamespace
+from vector_sdk.namespaces.db import DBNamespace
+from vector_sdk.namespaces.embeddings import EmbeddingsNamespace
+from vector_sdk.namespaces.search import SearchNamespace
+
+__all__ = [
+    "BaseNamespace",
+    "EmbeddingsNamespace",
+    "SearchNamespace",
+    "DBNamespace",
+]

vector_sdk/namespaces/base.py

@@ -0,0 +1,45 @@
+"""
+Base namespace class providing shared context for all namespace implementations.
+"""
+
+from typing import Optional
+
+from redis import Redis
+
+
+class BaseNamespace:
+    """
+    Base class for all namespace implementations.
+    Provides access to shared Redis and HTTP clients.
+    """
+
+    def __init__(self, redis: Redis, http_url: Optional[str] = None):
+        """
+        Initialize the base namespace.
+
+        Args:
+            redis: Redis client instance
+            http_url: Optional HTTP URL for query-gateway API
+        """
+        self._redis = redis
+        self._http_url = http_url
+
+    def _require_http_url(self, method_name: str) -> str:
+        """
+        Helper to require http_url for HTTP-based operations.
+
+        Args:
+            method_name: Name of the method requiring http_url
+
+        Returns:
+            The http_url
+
+        Raises:
+            ValueError: If http_url is not configured
+        """
+        if not self._http_url:
+            raise ValueError(
+                f"http_url is required for {method_name}. "
+                "Set it in VectorClient constructor."
+            )
+        return self._http_url