featrixsphere 0.2.5566__py3-none-any.whl → 0.2.5978__py3-none-any.whl

featrixsphere/api/reference_record.py

@@ -0,0 +1,227 @@
+"""
+ReferenceRecord class for FeatrixSphere API.
+
+Represents a reference point in the embedding space for similarity search.
+Useful when you only have positive examples and want to find similar records.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, Any, Optional, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http_client import ClientContext
+    from .foundational_model import FoundationalModel
+    from .vector_database import VectorDatabase
+    import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReferenceRecord:
+    """
+    Represents a reference record in the embedding space.
+
+    A ReferenceRecord is useful when you only have positive examples but no
+    negative examples. Instead of training a classifier, you can create a
+    reference from a positive example and find similar records.
+
+    Attributes:
+        id: ReferenceRecord ID
+        name: Optional name
+        session_id: Parent session ID
+        record: The record this reference represents
+        embedding: Cached embedding vector
+        created_at: Creation timestamp
+
+    Usage:
+        # Create from foundational model
+        ref = fm.create_reference_record(
+            record={"age": 35, "income": 50000},
+            name="target_profile"
+        )
+
+        # Find similar records
+        similar = ref.find_similar(k=10, vector_database=vdb)
+
+        # Get embedding
+        embedding = ref.get_embedding()
+    """
+
+    id: str
+    session_id: str
+    record: Dict[str, Any]
+    name: Optional[str] = None
+    embedding: Optional[List[float]] = None
+    created_at: Optional[datetime] = None
+
+    # Internal
+    _ctx: Optional['ClientContext'] = field(default=None, repr=False)
+    _foundational_model: Optional['FoundationalModel'] = field(default=None, repr=False)
+
+    @classmethod
+    def from_record(
+        cls,
+        record: Dict[str, Any],
+        session_id: str,
+        name: Optional[str] = None,
+        ctx: Optional['ClientContext'] = None,
+        foundational_model: Optional['FoundationalModel'] = None
+    ) -> 'ReferenceRecord':
+        """
+        Create a ReferenceRecord from a record.
+
+        Args:
+            record: The record to create reference from
+            session_id: Parent session ID
+            name: Optional name
+            ctx: Client context for API calls
+            foundational_model: Parent FM
+
+        Returns:
+            ReferenceRecord instance
+        """
+        import uuid
+
+        ref = cls(
+            id=str(uuid.uuid4()),
+            session_id=session_id,
+            record=record,
+            name=name,
+            created_at=datetime.now(),
+            _ctx=ctx,
+            _foundational_model=foundational_model,
+        )
+
+        # Pre-compute embedding if we have context
+        if ctx:
+            try:
+                ref._compute_embedding()
+            except Exception as e:
+                logger.warning(f"Failed to compute embedding for reference record: {e}")
+
+        return ref
+
+    @property
+    def foundational_model(self) -> Optional['FoundationalModel']:
+        """Get the parent foundational model."""
+        return self._foundational_model
+
+    def find_similar(
+        self,
+        k: int = 10,
+        vector_database: Optional['VectorDatabase'] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Find k records similar to this reference.
+
+        Args:
+            k: Number of similar records to return
+            vector_database: Optional VectorDatabase to search in.
+                           If None, searches in the session's default records.
+
+        Returns:
+            List of similar records with similarity scores
+
+        Example:
+            similar = ref.find_similar(k=10)
+            for record in similar:
+                print(f"Score: {record['similarity']}")
+                print(f"Data: {record['record']}")
+        """
+        if not self._ctx:
+            raise ValueError("ReferenceRecord not connected to client")
+
+        # If vector database provided, use it
+        if vector_database:
+            return vector_database.similarity_search(self.record, k=k)
+
+        # Otherwise use session-level similarity search
+        cleaned_record = self._clean_record(self.record)
+
+        response = self._ctx.post_json(
+            f"/session/{self.session_id}/similarity_search",
+            data={
+                "query_record": cleaned_record,
+                "k": k
+            }
+        )
+
+        return response.get('similar_records', response.get('results', []))
+
+    def get_embedding(self) -> List[float]:
+        """
+        Get the embedding vector for this reference record.
+
+        Returns:
+            List of floats representing the embedding vector
+
+        Example:
+            embedding = ref.get_embedding()
+            print(f"Embedding dimension: {len(embedding)}")
+        """
+        if self.embedding is not None:
+            return self.embedding
+
+        self._compute_embedding()
+        return self.embedding or []
+
+    def _compute_embedding(self) -> None:
+        """Compute and cache the embedding for this reference's record."""
+        if not self._ctx:
+            raise ValueError("ReferenceRecord not connected to client")
+
+        cleaned_record = self._clean_record(self.record)
+
+        response = self._ctx.post_json(
+            f"/session/{self.session_id}/encode_records",
+            data={"records": [cleaned_record]}
+        )
+
+        embeddings = response.get('embeddings', [])
+        if embeddings:
+            self.embedding = embeddings[0]
+
+    def delete(self) -> None:
+        """
+        Delete this reference record.
+
+        Note: ReferenceRecords are lightweight and exist only in memory on the client.
+        This method clears the reference's data.
+        """
+        self.record = {}
+        self.embedding = None
+        self._ctx = None
+        self._foundational_model = None
+
+    def _clean_record(self, record: Dict[str, Any]) -> Dict[str, Any]:
+        """Clean a record for API submission."""
+        import math
+
+        cleaned = {}
+        for key, value in record.items():
+            if isinstance(value, float):
+                if math.isnan(value) or math.isinf(value):
+                    value = None
+            if hasattr(value, 'item'):
+                value = value.item()
+            cleaned[key] = value
+        return cleaned
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            'id': self.id,
+            'session_id': self.session_id,
+            'name': self.name,
+            'record': self.record,
+            'embedding_dimension': len(self.embedding) if self.embedding else None,
+            'created_at': self.created_at.isoformat() if self.created_at else None,
+        }
+
+    def __repr__(self) -> str:
+        name_str = f", name='{self.name}'" if self.name else ""
+        emb_str = f", dim={len(self.embedding)}" if self.embedding else ""
+        return f"ReferenceRecord(id='{self.id}'{name_str}{emb_str})"

featrixsphere/api/vector_database.py

@@ -0,0 +1,269 @@
+"""
+VectorDatabase class for FeatrixSphere API.
+
+Represents a vector database for similarity search operations.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, Any, Optional, List, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http_client import ClientContext
+    from .foundational_model import FoundationalModel
+    import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class VectorDatabase:
+    """
+    Represents a vector database for similarity search.
+
+    Attributes:
+        id: Vector database ID (same as session_id)
+        name: Database name
+        session_id: Parent session ID
+        record_count: Number of records in database
+        created_at: Creation timestamp
+
+    Usage:
+        # Create from foundational model
+        vdb = fm.create_vector_database(
+            name="customer_search",
+            records=customer_records
+        )
+
+        # Similarity search
+        similar = vdb.similarity_search(
+            {"age": 35, "income": 50000},
+            k=5
+        )
+
+        # Add more records
+        vdb.add_records(new_customers)
+    """
+
+    id: str
+    session_id: str
+    name: Optional[str] = None
+    record_count: int = 0
+    created_at: Optional[datetime] = None
+
+    # Internal
+    _ctx: Optional['ClientContext'] = field(default=None, repr=False)
+    _foundational_model: Optional['FoundationalModel'] = field(default=None, repr=False)
+
+    @classmethod
+    def from_session(
+        cls,
+        session_id: str,
+        name: Optional[str] = None,
+        ctx: Optional['ClientContext'] = None,
+        foundational_model: Optional['FoundationalModel'] = None
+    ) -> 'VectorDatabase':
+        """Create VectorDatabase from session ID."""
+        vdb = cls(
+            id=session_id,
+            session_id=session_id,
+            name=name,
+            created_at=datetime.now(),
+            _ctx=ctx,
+            _foundational_model=foundational_model,
+        )
+
+        # Try to get record count
+        if ctx:
+            try:
+                size = ctx.get_json(f"/session/{session_id}/vectordb_size")
+                vdb.record_count = size.get('size', 0)
+            except Exception:
+                pass
+
+        return vdb
+
+    @property
+    def foundational_model(self) -> Optional['FoundationalModel']:
+        """Get the parent foundational model."""
+        return self._foundational_model
+
+    def similarity_search(
+        self,
+        query_record: Dict[str, Any],
+        k: int = 10
+    ) -> List[Dict[str, Any]]:
+        """
+        Find k most similar records to the query.
+
+        Args:
+            query_record: Query record dictionary
+            k: Number of similar records to return
+
+        Returns:
+            List of similar records with similarity scores
+
+        Example:
+            similar = vdb.similarity_search(
+                {"age": 35, "income": 50000},
+                k=5
+            )
+            for record in similar:
+                print(f"Score: {record['similarity']}")
+                print(f"Data: {record['record']}")
+        """
+        if not self._ctx:
+            raise ValueError("VectorDatabase not connected to client")
+
+        cleaned_query = self._clean_record(query_record)
+
+        response = self._ctx.post_json(
+            f"/session/{self.session_id}/similarity_search",
+            data={
+                "query_record": cleaned_query,
+                "k": k
+            }
+        )
+
+        return response.get('similar_records', response.get('results', []))
+
+    def add_records(
+        self,
+        records: Union[List[Dict[str, Any]], 'pd.DataFrame'],
+        batch_size: int = 500
+    ) -> 'VectorDatabase':
+        """
+        Add records to the vector database.
+
+        Args:
+            records: List of record dictionaries or DataFrame
+            batch_size: Batch size for adding records
+
+        Returns:
+            Self (updated record count)
+        """
+        if not self._ctx:
+            raise ValueError("VectorDatabase not connected to client")
+
+        # Convert DataFrame to list if needed
+        if hasattr(records, 'to_dict'):
+            records = records.to_dict('records')
+
+        # Clean records
+        cleaned_records = [self._clean_record(r) for r in records]
+
+        # Add in batches
+        total_added = 0
+        for i in range(0, len(cleaned_records), batch_size):
+            batch = cleaned_records[i:i + batch_size]
+
+            response = self._ctx.post_json(
+                f"/session/{self.session_id}/add_records",
+                data={"records": batch}
+            )
+
+            added = response.get('added', len(batch))
+            total_added += added
+
+        self.record_count += total_added
+        return self
+
+    def remove_records(
+        self,
+        record_ids: List[str]
+    ) -> 'VectorDatabase':
+        """
+        Remove records from the vector database by ID.
+
+        Args:
+            record_ids: List of record IDs to remove
+
+        Returns:
+            Self (updated record count)
+
+        Note:
+            This operation may not be supported by all backends.
+        """
+        if not self._ctx:
+            raise ValueError("VectorDatabase not connected to client")
+
+        # This endpoint may not exist yet - placeholder for future
+        try:
+            response = self._ctx.post_json(
+                f"/session/{self.session_id}/remove_records",
+                data={"record_ids": record_ids}
+            )
+            removed = response.get('removed', len(record_ids))
+            self.record_count = max(0, self.record_count - removed)
+        except Exception as e:
+            logger.warning(f"remove_records not supported: {e}")
+
+        return self
+
+    def size(self) -> int:
+        """Get the current number of records in the database."""
+        if not self._ctx:
+            raise ValueError("VectorDatabase not connected to client")
+
+        response = self._ctx.get_json(f"/session/{self.session_id}/vectordb_size")
+        self.record_count = response.get('size', 0)
+        return self.record_count
+
+    def encode(
+        self,
+        records: Union[Dict[str, Any], List[Dict[str, Any]], 'pd.DataFrame']
+    ) -> List[List[float]]:
+        """
+        Encode records to embedding vectors.
+
+        Args:
+            records: Single record, list of records, or DataFrame
+
+        Returns:
+            List of embedding vectors
+        """
+        if not self._ctx:
+            raise ValueError("VectorDatabase not connected to client")
+
+        # Normalize input to list
+        if isinstance(records, dict):
+            records = [records]
+        elif hasattr(records, 'to_dict'):
+            records = records.to_dict('records')
+
+        cleaned_records = [self._clean_record(r) for r in records]
+
+        response = self._ctx.post_json(
+            f"/session/{self.session_id}/encode_records",
+            data={"records": cleaned_records}
+        )
+
+        return response.get('embeddings', [])
+
+    def _clean_record(self, record: Dict[str, Any]) -> Dict[str, Any]:
+        """Clean a record for API submission."""
+        import math
+
+        cleaned = {}
+        for key, value in record.items():
+            if isinstance(value, float):
+                if math.isnan(value) or math.isinf(value):
+                    value = None
+            if hasattr(value, 'item'):
+                value = value.item()
+            cleaned[key] = value
+        return cleaned
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            'id': self.id,
+            'session_id': self.session_id,
+            'name': self.name,
+            'record_count': self.record_count,
+            'created_at': self.created_at.isoformat() if self.created_at else None,
+        }
+
+    def __repr__(self) -> str:
+        return f"VectorDatabase(id='{self.id}', name='{self.name}', records={self.record_count})"