featrixsphere 0.2.6379__tar.gz → 0.2.6710__tar.gz

{featrixsphere-0.2.6379 → featrixsphere-0.2.6710}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: featrixsphere
-Version: 0.2.6379
+Version: 0.2.6710
 Summary: Transform any CSV into a production-ready ML model in minutes, not months.
 Home-page: https://github.com/Featrix/sphere
 Author: Featrix

featrixsphere-0.2.6710/VERSION

@@ -0,0 +1 @@
+0.2.6710

{featrixsphere-0.2.6379 → featrixsphere-0.2.6710}/featrixsphere/__init__.py

@@ -57,7 +57,7 @@ TWO API OPTIONS:
     >>> print(result['prediction'])
 """
 
-__version__ = "0.2.6379"
+__version__ = "0.2.6710"
 __author__ = "Featrix"
 __email__ = "support@featrix.com"
 __license__ = "MIT"

{featrixsphere-0.2.6379 → featrixsphere-0.2.6710}/featrixsphere/api/client.py

@@ -342,6 +342,34 @@ class FeatrixSphere(HTTPClientMixin):
             ground_truth=ground_truth
         )
 
+    def list_sessions(
+        self,
+        name_prefix: str = "",
+    ) -> List[str]:
+        """
+        List sessions matching a name prefix/search term.
+
+        Searches session directory names on the compute cluster for
+        partial matches (not just prefix).
+
+        Args:
+            name_prefix: Term to match in session names
+
+        Returns:
+            List of matching session ID strings
+
+        Example:
+            sessions = featrix.list_sessions(name_prefix="customer")
+            for sid in sessions:
+                fm = featrix.foundational_model(sid)
+                print(f"{sid}: {fm.status}")
+        """
+        params = {}
+        if name_prefix:
+            params['name_prefix'] = name_prefix
+        response = self._get_json("/compute/sessions-for-org", params=params)
+        return response.get('sessions', [])
+
     def health_check(self) -> Dict[str, Any]:
         """
         Check if the API server is healthy.

{featrixsphere-0.2.6379 → featrixsphere-0.2.6710}/featrixsphere/api/foundational_model.py

@@ -22,6 +22,21 @@ from .reference_record import ReferenceRecord
 logger = logging.getLogger(__name__)
 
 
+def _parse_datetime(value) -> Optional[datetime]:
+    """Parse a datetime from ISO string or return as-is if already datetime."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        try:
+            # Handle ISO format with or without timezone
+            return datetime.fromisoformat(value.replace('Z', '+00:00'))
+        except (ValueError, AttributeError):
+            return None
+    return None
+
+
 @dataclass
 class FoundationalModel:
     """
@@ -68,6 +83,11 @@ class FoundationalModel:
     epochs: Optional[int] = None
     final_loss: Optional[float] = None
     created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    session_type: Optional[str] = None
+    compute_cluster: Optional[str] = None
+    error_message: Optional[str] = None
+    training_progress: Optional[Dict[str, Any]] = None
 
     # Internal
     _ctx: Optional['ClientContext'] = field(default=None, repr=False)
@@ -88,7 +108,9 @@ class FoundationalModel:
             dimensions=response.get('d_model') or response.get('dimensions'),
             epochs=response.get('epochs') or response.get('final_epoch'),
             final_loss=response.get('final_loss'),
-            created_at=datetime.now(),
+            created_at=_parse_datetime(response.get('created_at')),
+            session_type=response.get('session_type'),
+            compute_cluster=response.get('compute_cluster'),
             _ctx=ctx,
         )
 
@@ -99,19 +121,22 @@ class FoundationalModel:
         ctx: 'ClientContext'
     ) -> 'FoundationalModel':
         """Load FoundationalModel from session ID."""
-        # Get session info
-        session_data = ctx.get_json(f"/compute/session/{session_id}")
+        # Get session info - response has {"session": {...}, "jobs": {...}}
+        response_data = ctx.get_json(f"/compute/session/{session_id}")
+        session = response_data.get('session', response_data)
 
         fm = cls(
             id=session_id,
-            name=session_data.get('name'),
-            status=session_data.get('status'),
-            created_at=datetime.now(),
+            name=session.get('name'),
+            status=session.get('status'),
+            created_at=_parse_datetime(session.get('created_at')),
+            session_type=session.get('session_type'),
+            compute_cluster=session.get('compute_cluster'),
             _ctx=ctx,
         )
 
-        # Try to get model info
-        fm._update_from_session(session_data)
+        # Extract model info, training stats, jobs, error_message
+        fm._update_from_session(response_data)
 
         return fm
 
@@ -439,10 +464,11 @@ class FoundationalModel:
         last_status = None
 
         while time.time() - start_time < max_wait_time:
-            # Get session status
-            session_data = self._ctx.get_json(f"/compute/session/{self.id}")
+            # Get session status - response has {"session": {...}, "jobs": {...}}
+            response_data = self._ctx.get_json(f"/compute/session/{self.id}")
+            session_data = response_data.get('session', response_data)
             status = session_data.get('status', 'unknown')
-            jobs = session_data.get('jobs', {})
+            jobs = response_data.get('jobs', {})
 
             # Look for ES training job
             es_job = None
@@ -475,7 +501,7 @@ class FoundationalModel:
             # Check completion
             if job_status == 'done' or status == 'done':
                 self.status = 'done'
-                self._update_from_session(session_data)
+                self._update_from_session(response_data)
                 if show_progress:
                     print(f"Training complete!")
                     if self.dimensions:
@@ -566,6 +592,28 @@ class FoundationalModel:
 
         return self._ctx.get_json(f"/session/{self.id}/projections")
 
+    def get_sphere_preview(self, save_path: str = None) -> bytes:
+        """
+        Get the 2D sphere projection preview image (PNG).
+
+        Args:
+            save_path: Optional path to save the PNG file. If provided, the image
+                      will be written to this path.
+
+        Returns:
+            Raw PNG image bytes.
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        png_bytes = self._ctx.get_bytes(f"/session/{self.id}/preview")
+
+        if save_path:
+            with open(save_path, 'wb') as f:
+                f.write(png_bytes)
+
+        return png_bytes
+
     def get_training_metrics(self) -> Dict[str, Any]:
         """Get training metrics and history."""
         if not self._ctx:
@@ -605,27 +653,73 @@ class FoundationalModel:
 
         return predictors
 
-    def _update_from_session(self, session_data: Dict[str, Any]) -> None:
-        """Update fields from session data."""
-        # Try to get model info from various places
-        model_info = session_data.get('model_info', {})
-        training_stats = session_data.get('training_stats', {})
+    def _update_from_session(self, response_data: Dict[str, Any]) -> None:
+        """Update fields from session API response.
+
+        The response from GET /session/{id} has structure:
+            {"session": {...}, "jobs": {...}, ...}
+        """
+        # Handle both nested and flat response formats
+        session = response_data.get('session', response_data)
+        jobs = response_data.get('jobs', {})
+
+        # Core session fields
+        if session.get('name') and not self.name:
+            self.name = session['name']
+        if session.get('status'):
+            self.status = session['status']
+        if session.get('session_type'):
+            self.session_type = session['session_type']
+        if session.get('compute_cluster'):
+            self.compute_cluster = session['compute_cluster']
+        if session.get('created_at') and not self.created_at:
+            self.created_at = _parse_datetime(session['created_at'])
+        if session.get('finished_at'):
+            self.updated_at = _parse_datetime(session['finished_at'])
+        elif session.get('started_at'):
+            self.updated_at = _parse_datetime(session['started_at'])
+
+        # Model info from session
+        model_info = session.get('model_info', {})
+        training_stats = session.get('training_stats', {})
 
         self.dimensions = (
             model_info.get('d_model') or
             model_info.get('embedding_dim') or
-            session_data.get('d_model')
+            session.get('d_model')
         )
         self.epochs = (
             training_stats.get('final_epoch') or
             training_stats.get('epochs_trained') or
-            session_data.get('epochs')
+            session.get('epochs')
         )
         self.final_loss = (
             training_stats.get('final_loss') or
-            session_data.get('final_loss')
+            session.get('final_loss')
         )
 
+        # Extract error_message and training_progress from jobs
+        for job_id, job in jobs.items():
+            job_type = job.get('job_type', '')
+            job_status = job.get('status', '')
+
+            # Training progress from ES training job
+            if job_type in ('train_embedding_space', 'train_es', 'training'):
+                current_epoch = job.get('current_epoch') or job.get('epoch')
+                total_epochs = job.get('total_epochs') or job.get('epochs')
+                if current_epoch or total_epochs:
+                    self.training_progress = {
+                        'current_epoch': current_epoch,
+                        'total_epochs': total_epochs,
+                        'job_status': job_status,
+                    }
+
+            # Error message from any failed job
+            if job_status in ('failed', 'error'):
+                err = job.get('error') or job.get('error_message')
+                if err:
+                    self.error_message = err
+
     def _clean_record(self, record: Dict[str, Any]) -> Dict[str, Any]:
         """Clean a record for API submission."""
         import math
@@ -640,6 +734,281 @@ class FoundationalModel:
             cleaned[key] = value
         return cleaned
 
+    def get_columns(self) -> List[str]:
+        """
+        Get the column names in this foundational model's embedding space.
+
+        Returns:
+            List of column name strings
+
+        Example:
+            columns = fm.get_columns()
+            print(columns)  # ['age', 'income', 'city', ...]
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        response = self._ctx.get_json(f"/compute/session/{self.id}/columns")
+        return response.get('columns', [])
+
+    @property
+    def columns(self) -> List[str]:
+        """Column names in this foundational model's embedding space."""
+        return self.get_columns()
+
+    @property
+    def schema_metadata(self) -> Dict[str, Any]:
+        """Get schema metadata including column names and types.
+
+        Returns:
+            Dict with 'column_names', 'column_types', and 'num_columns'
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+        return self._ctx.get_json(f"/compute/session/{self.id}/columns")
+
+    def clone(
+        self,
+        target_compute_cluster: Optional[str] = None,
+        new_name: Optional[str] = None,
+        source_compute_cluster: Optional[str] = None,
+    ) -> 'FoundationalModel':
+        """
+        Clone this embedding space, optionally to a different compute node.
+
+        Args:
+            target_compute_cluster: Target compute cluster (None = same node)
+            new_name: Name for the cloned session
+            source_compute_cluster: Source compute cluster (if routing needed)
+
+        Returns:
+            New FoundationalModel instance for the cloned embedding space
+
+        Example:
+            cloned = fm.clone(
+                target_compute_cluster="churro",
+                new_name="my-model-clone"
+            )
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        data = {
+            "to_compute": target_compute_cluster,
+            "new_session_name": new_name,
+        }
+
+        response = self._ctx.post_json(
+            f"/compute/session/{self.id}/clone_embedding_space",
+            data=data
+        )
+
+        new_session_id = response.get('new_session_id', '')
+        return FoundationalModel(
+            id=new_session_id,
+            name=new_name,
+            status="done",
+            created_at=datetime.now(),
+            _ctx=self._ctx,
+        )
+
+    def refresh(self) -> Dict[str, Any]:
+        """
+        Refresh this foundational model's state from the server.
+
+        Returns the full server-side info for this model, and updates
+        local attributes (status, epochs, dimensions, etc.).
+
+        Returns:
+            Full model info dictionary from the server
+
+        Example:
+            info = fm.refresh()
+            print(fm.status)   # Updated from server
+            print(fm.epochs)   # Updated from server
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        data = self._ctx.get_json(f"/compute/session/{self.id}")
+        self._update_from_session(data)
+        return data
+
+    def is_ready(self) -> bool:
+        """
+        Check if this foundational model has finished training and is ready for use.
+
+        Returns:
+            True if training is complete, False otherwise
+
+        Example:
+            if fm.is_ready():
+                predictor = fm.create_classifier(target_column="target")
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        data = self._ctx.get_json(f"/compute/session/{self.id}")
+        self._update_from_session(data)
+        return self.status == 'done'
+
+    def publish(
+        self,
+        org_id: str,
+        name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Publish this foundational model to the production directory.
+
+        Published models are protected from garbage collection and available
+        across all compute nodes via the shared backplane.
+
+        Args:
+            org_id: Organization ID for directory organization
+            name: Name for the published model (defaults to self.name)
+
+        Returns:
+            dict with published_path, output_path, and status
+
+        Example:
+            fm = featrix.create_foundational_model(name="my_model", csv_file="data.csv")
+            fm.wait_for_training()
+            fm.publish(org_id="my_org", name="my_model_v1")
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        publish_name = name or self.name
+        if not publish_name:
+            raise ValueError("name is required (either pass it or set it on the model)")
+
+        data = {
+            "org_id": org_id,
+            "name": publish_name,
+        }
+        return self._ctx.post_json(f"/compute/session/{self.id}/publish", data=data)
+
+    def deprecate(
+        self,
+        warning_message: str,
+        expiration_date: str,
+    ) -> Dict[str, Any]:
+        """
+        Deprecate this published model with a warning and expiration date.
+
+        The model remains available until the expiration date. Prediction
+        responses will include a model_expiration field warning consumers.
+
+        Args:
+            warning_message: Warning message to display
+            expiration_date: ISO format date string (e.g., "2026-06-01T00:00:00Z")
+
+        Returns:
+            dict with deprecation status
+
+        Example:
+            from datetime import datetime, timedelta
+            expiration = (datetime.now() + timedelta(days=90)).isoformat() + "Z"
+            fm.deprecate(
+                warning_message="Replaced by v2. Migrate by expiration.",
+                expiration_date=expiration
+            )
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        data = {
+            "warning_message": warning_message,
+            "expiration_date": expiration_date,
+        }
+        return self._ctx.post_json(f"/compute/session/{self.id}/deprecate", data=data)
+
+    def unpublish(self) -> Dict[str, Any]:
+        """
+        Unpublish this model, moving it back from the published directory.
+
+        WARNING: After unpublishing, the model is subject to garbage
+        collection and may be deleted when disk space is low.
+
+        Returns:
+            dict with unpublish status
+
+        Example:
+            fm.unpublish()
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        return self._ctx.post_json(f"/compute/session/{self.id}/unpublish", data={})
+
+    def publish_checkpoint(
+        self,
+        name: str,
+        org_id: Optional[str] = None,
+        checkpoint_epoch: Optional[int] = None,
+        session_name_prefix: Optional[str] = None,
+        publish: bool = True,
+    ) -> 'FoundationalModel':
+        """
+        Publish a checkpoint from this model's training as a new foundation model.
+
+        Creates a NEW FoundationalModel from a training checkpoint with full
+        provenance tracking. Useful for snapshotting good intermediate models
+        while training continues.
+
+        Args:
+            name: Name for the new foundation model (required)
+            org_id: Organization ID (required if publish=True)
+            checkpoint_epoch: Which epoch checkpoint to use (None = best/latest)
+            session_name_prefix: Optional prefix for the new session ID
+            publish: Move to published directory (default: True)
+
+        Returns:
+            New FoundationalModel instance for the published checkpoint
+
+        Example:
+            # Snapshot epoch 50 while training continues
+            checkpoint_fm = fm.publish_checkpoint(
+                name="My Model v0.5",
+                org_id="my_org",
+                checkpoint_epoch=50
+            )
+            # Use immediately
+            predictor = checkpoint_fm.create_classifier(target_column="target")
+        """
+        if not self._ctx:
+            raise ValueError("FoundationalModel not connected to client")
+
+        if publish and not org_id:
+            raise ValueError("org_id is required when publish=True")
+
+        data = {
+            "name": name,
+            "publish": publish,
+        }
+        if checkpoint_epoch is not None:
+            data["checkpoint_epoch"] = checkpoint_epoch
+        if session_name_prefix:
+            data["session_name_prefix"] = session_name_prefix
+        if org_id:
+            data["org_id"] = org_id
+
+        response = self._ctx.post_json(
+            f"/compute/session/{self.id}/publish_partial_foundation",
+            data=data
+        )
+
+        new_fm = FoundationalModel(
+            id=response.get("foundation_session_id", ""),
+            name=name,
+            status="done",
+            epochs=response.get("checkpoint_epoch"),
+            created_at=datetime.now(),
+            _ctx=self._ctx,
+        )
+
+        return new_fm
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary representation."""
         return {
@@ -650,6 +1019,11 @@ class FoundationalModel:
             'epochs': self.epochs,
             'final_loss': self.final_loss,
             'created_at': self.created_at.isoformat() if self.created_at else None,
+            'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+            'session_type': self.session_type,
+            'compute_cluster': self.compute_cluster,
+            'error_message': self.error_message,
+            'training_progress': self.training_progress,
         }
 
     def __repr__(self) -> str:

{featrixsphere-0.2.6379 → featrixsphere-0.2.6710}/featrixsphere/api/http_client.py

@@ -121,14 +121,34 @@ class HTTPClientMixin:
 
     def _unwrap_response(self, response_json: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Unwrap server response, handling the 'response' wrapper if present.
+        Unwrap server response, handling wrapper formats.
 
-        The server sometimes wraps responses in {"response": {...}}.
+        The server may wrap responses as:
+        - {"response": {...}}
+        - {"_meta": {...}, "data": {...}}
+
+        Captures server metadata when present.
         """
-        if isinstance(response_json, dict) and 'response' in response_json and len(response_json) == 1:
-            return response_json['response']
+        if isinstance(response_json, dict):
+            # Handle _meta/data wrapper (captures server metadata)
+            if '_meta' in response_json and 'data' in response_json:
+                self._last_server_metadata = response_json['_meta']
+                return response_json['data']
+            # Handle response wrapper
+            if 'response' in response_json and len(response_json) == 1:
+                return response_json['response']
         return response_json
 
+    @property
+    def last_server_metadata(self) -> Optional[Dict[str, Any]]:
+        """
+        Metadata from the most recent server response.
+
+        Contains server info like compute_cluster_time, compute_cluster,
+        compute_cluster_version, etc.
+        """
+        return getattr(self, '_last_server_metadata', None)
+
     def _get_json(
         self,
         endpoint: str,
@@ -139,6 +159,16 @@ class HTTPClientMixin:
         response = self._make_request("GET", endpoint, max_retries=max_retries, **kwargs)
         return self._unwrap_response(response.json())
 
+    def _get_bytes(
+        self,
+        endpoint: str,
+        max_retries: Optional[int] = None,
+        **kwargs
+    ) -> bytes:
+        """Make a GET request and return raw bytes (for binary content like images)."""
+        response = self._make_request("GET", endpoint, max_retries=max_retries, **kwargs)
+        return response.content
+
     def _post_json(
         self,
         endpoint: str,
@@ -207,3 +237,6 @@ class ClientContext:
     def post_multipart(self, endpoint: str, data: Dict[str, Any] = None,
                        files: Dict[str, Any] = None, **kwargs) -> Dict[str, Any]:
         return self._client._post_multipart(endpoint, data, files, **kwargs)
+
+    def get_bytes(self, endpoint: str, **kwargs) -> bytes:
+        return self._client._get_bytes(endpoint, **kwargs)