featrixsphere 0.2.6379__tar.gz → 0.2.6708__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: featrixsphere
-Version: 0.2.6379
+Version: 0.2.6708
 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.6708/VERSION

@@ -0,0 +1 @@
+0.2.6708

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

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

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

@@ -566,6 +566,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:
@@ -640,6 +662,272 @@ 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()
+
+    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)
+        self.status = data.get('status', self.status)
+        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}")
+        status = data.get('status', 'unknown')
+        self.status = status
+        return 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 {

{featrixsphere-0.2.6379 → featrixsphere-0.2.6708}/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)

{featrixsphere-0.2.6379 → featrixsphere-0.2.6708}/featrixsphere/api/prediction_result.py

@@ -23,11 +23,16 @@ class PredictionResult:
         prediction: Raw prediction result (class probabilities or numeric value)
         predicted_class: Predicted class name (for classification)
         confidence: Confidence score (for classification)
+        probabilities: Full probability distribution (for classification)
+        threshold: Classification threshold (for binary classification)
         query_record: Original input record
         predictor_id: ID of predictor that made this prediction
         session_id: Session ID (internal)
         timestamp: When prediction was made
         target_column: Target column name
+        guardrails: Per-column guardrail warnings (if any)
+        ignored_query_columns: Columns in input that were not used (not in training data)
+        available_query_columns: All columns the model knows about
 
     Usage:
         result = predictor.predict({"age": 35, "income": 50000})
@@ -35,6 +40,14 @@ class PredictionResult:
         print(result.confidence)       # 0.87
         print(result.prediction_uuid)  # UUID for feedback
 
+        # Check for guardrail warnings
+        if result.guardrails:
+            print(f"Warnings: {len(result.guardrails)} columns with issues")
+
+        # Check for ignored columns
+        if result.ignored_query_columns:
+            print(f"Ignored: {result.ignored_query_columns}")
+
         # Send feedback if prediction was wrong
         if result.predicted_class != actual_label:
             feedback = result.send_feedback(ground_truth=actual_label)
@@ -44,14 +57,52 @@ class PredictionResult:
     prediction_uuid: Optional[str] = None
     prediction: Optional[Union[Dict[str, float], float]] = None
     predicted_class: Optional[str] = None
+    probability: Optional[float] = None
     confidence: Optional[float] = None
+    probabilities: Optional[Dict[str, float]] = None
+    threshold: Optional[float] = None
     query_record: Optional[Dict[str, Any]] = None
+
+    # Documentation fields - explain what prediction/probability/confidence mean
+    readme_prediction: str = field(default="The predicted class label (for classification) or value (for regression).")
+    readme_probability: str = field(default="Raw probability of the predicted class from the model's softmax output.")
+    readme_confidence: str = field(default=(
+        "For binary classification: normalized margin from threshold. "
+        "confidence = (prob - threshold) / (1 - threshold) if predicting positive, "
+        "or (threshold - prob) / threshold if predicting negative. "
+        "Ranges from 0 (at decision boundary) to 1 (maximally certain). "
+        "For multi-class: same as probability."
+    ))
+    readme_threshold: str = field(default=(
+        "Decision boundary for binary classification. "
+        "If P(positive_class) >= threshold, predict positive; otherwise predict negative. "
+        "Calibrated to optimize F1 score on validation data."
+    ))
+    readme_probabilities: str = field(default=(
+        "Full probability distribution across all classes from the model's softmax output. "
+        "Dictionary mapping class labels to their probabilities (sum to 1.0)."
+    ))
+    readme_pos_label: str = field(default=(
+        "The class label considered 'positive' for binary classification metrics. "
+        "Threshold and confidence calculations are relative to this class."
+    ))
     predictor_id: Optional[str] = None
     session_id: Optional[str] = None
     target_column: Optional[str] = None
     timestamp: Optional[datetime] = None
     model_version: Optional[str] = None
 
+    # Checkpoint info from the model (epoch, metric_type, metric_value)
+    checkpoint_info: Optional[Dict[str, Any]] = None
+
+    # Guardrails and warnings
+    guardrails: Optional[Dict[str, Any]] = None
+    ignored_query_columns: Optional[list] = None
+    available_query_columns: Optional[list] = None
+
+    # Feature importance (from leave-one-out ablation)
+    feature_importance: Optional[Dict[str, float]] = None
+
     # Internal: client context for sending feedback
     _ctx: Optional['ClientContext'] = field(default=None, repr=False)
 
@@ -73,29 +124,44 @@ class PredictionResult:
         Returns:
             PredictionResult instance
         """
-        # Extract prediction data
+        # Extract prediction data - handle both formats
+        # New format: prediction is the class label, probabilities is separate
+        # Old format: prediction is the probabilities dict
         prediction = response.get('prediction')
-        predicted_class = None
-        confidence = None
-
-        # For classification, extract class and confidence
-        if isinstance(prediction, dict):
-            # Find the class with highest probability
+        probabilities = response.get('probabilities')
+        predicted_class = response.get('predicted_class')
+        probability = response.get('probability')
+        confidence = response.get('confidence')
+
+        # For old format where prediction is the probabilities dict
+        if isinstance(prediction, dict) and not probabilities:
+            probabilities = prediction
             if prediction:
                 predicted_class = max(prediction.keys(), key=lambda k: prediction[k])
-                confidence = prediction[predicted_class]
+                probability = prediction[predicted_class]
+                confidence = probability  # Old format: confidence = probability
+        elif isinstance(prediction, str) and not predicted_class:
+            # New format: prediction is already the class label
+            predicted_class = prediction
 
         return cls(
             prediction_uuid=response.get('prediction_uuid') or response.get('prediction_id'),
             prediction=prediction,
             predicted_class=predicted_class,
+            probability=probability,
             confidence=confidence,
+            probabilities=probabilities,
+            threshold=response.get('threshold'),
             query_record=query_record,
             predictor_id=response.get('predictor_id'),
             session_id=response.get('session_id'),
             target_column=response.get('target_column'),
             timestamp=datetime.now(),
             model_version=response.get('model_version'),
+            checkpoint_info=response.get('checkpoint_info'),
+            guardrails=response.get('guardrails'),
+            ignored_query_columns=response.get('ignored_query_columns'),
+            available_query_columns=response.get('available_query_columns'),
             _ctx=ctx,
         )
 
@@ -126,18 +192,41 @@ class PredictionResult:
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary representation."""
-        return {
+        result = {
             'prediction_uuid': self.prediction_uuid,
             'prediction': self.prediction,
             'predicted_class': self.predicted_class,
+            'probability': self.probability,
             'confidence': self.confidence,
+            'probabilities': self.probabilities,
+            'threshold': self.threshold,
             'query_record': self.query_record,
             'predictor_id': self.predictor_id,
             'session_id': self.session_id,
             'target_column': self.target_column,
             'timestamp': self.timestamp.isoformat() if self.timestamp else None,
             'model_version': self.model_version,
+            # Documentation
+            'readme_prediction': self.readme_prediction,
+            'readme_probability': self.readme_probability,
+            'readme_confidence': self.readme_confidence,
+            'readme_threshold': self.readme_threshold,
+            'readme_probabilities': self.readme_probabilities,
+            'readme_pos_label': self.readme_pos_label,
         }
+        # Include checkpoint_info if present
+        if self.checkpoint_info:
+            result['checkpoint_info'] = self.checkpoint_info
+        # Include guardrails if present
+        if self.guardrails:
+            result['guardrails'] = self.guardrails
+        if self.ignored_query_columns:
+            result['ignored_query_columns'] = self.ignored_query_columns
+        if self.available_query_columns:
+            result['available_query_columns'] = self.available_query_columns
+        if self.feature_importance:
+            result['feature_importance'] = self.feature_importance
+        return result
 
 
 @dataclass

{featrixsphere-0.2.6379 → featrixsphere-0.2.6708}/featrixsphere/api/predictor.py

@@ -105,7 +105,8 @@ class Predictor:
     def predict(
         self,
         record: Dict[str, Any],
-        best_metric_preference: Optional[str] = None
+        best_metric_preference: Optional[str] = None,
+        feature_importance: bool = False
     ) -> PredictionResult:
         """
         Make a single prediction.
@@ -113,15 +114,21 @@ class Predictor:
         Args:
             record: Input record dictionary
             best_metric_preference: Metric checkpoint to use ("roc_auc", "pr_auc", or None)
+            feature_importance: If True, compute feature importance via leave-one-out ablation
 
         Returns:
-            PredictionResult with prediction, confidence, and prediction_uuid
+            PredictionResult with prediction, confidence, and prediction_uuid.
+            If feature_importance=True, also includes feature_importance dict.
 
         Example:
             result = predictor.predict({"age": 35, "income": 50000})
             print(result.predicted_class)  # "churned"
             print(result.confidence)       # 0.87
             print(result.prediction_uuid)  # UUID for feedback
+
+            # With feature importance
+            result = predictor.predict(record, feature_importance=True)
+            print(result.feature_importance)  # {"income": 0.15, "age": 0.08, ...}
         """
         if not self._ctx:
             raise ValueError("Predictor not connected to client")
@@ -129,7 +136,44 @@ class Predictor:
         # Clean the record
         cleaned_record = self._clean_record(record)
 
-        # Build request
+        if feature_importance:
+            # Build N+1 records: original + each feature nulled out
+            columns = list(cleaned_record.keys())
+            batch = [cleaned_record]  # Original first
+
+            for col in columns:
+                ablated = cleaned_record.copy()
+                ablated[col] = None
+                batch.append(ablated)
+
+            # Single batch call
+            results = self.batch_predict(
+                batch,
+                show_progress=False,
+                best_metric_preference=best_metric_preference
+            )
+
+            # Compare: importance = |original_confidence - ablated_confidence|
+            original = results[0]
+            importance = {}
+            original_conf = original.confidence or 0.0
+
+            for i, col in enumerate(columns):
+                ablated_result = results[i + 1]
+                ablated_conf = ablated_result.confidence or 0.0
+                # Higher delta = more important
+                delta = abs(original_conf - ablated_conf)
+                importance[col] = round(delta, 4)
+
+            # Sort by importance (highest first)
+            original.feature_importance = dict(sorted(
+                importance.items(),
+                key=lambda x: x[1],
+                reverse=True
+            ))
+            return original
+
+        # Standard single prediction
         request_payload = {
             "query_record": cleaned_record,
             "predictor_id": self.id,
@@ -196,6 +240,36 @@ class Predictor:
 
         return results
 
+    def predict_csv_file(
+        self,
+        csv_path: str,
+        show_progress: bool = True,
+        best_metric_preference: Optional[str] = None
+    ) -> List[PredictionResult]:
+        """
+        Load a CSV file and run batch predictions on all rows.
+
+        Args:
+            csv_path: Path to the CSV file
+            show_progress: Show progress bar
+            best_metric_preference: Metric checkpoint to use
+
+        Returns:
+            List of PredictionResult objects
+
+        Example:
+            results = predictor.predict_csv_file("test_data.csv")
+            for r in results:
+                print(r.predicted_class, r.confidence)
+        """
+        import pandas as pd
+        df = pd.read_csv(csv_path)
+        return self.batch_predict(
+            df,
+            show_progress=show_progress,
+            best_metric_preference=best_metric_preference
+        )
+
     def explain(
         self,
         record: Dict[str, Any],