Featrix API Usage

1. Account Setup

Create an account and log in at https://app.featrix.com.

2. Generate API Key

• Navigate to API Keys at the bottom of the left-hand menu.

• Click Create New API Key, name your key, and save the Client ID and Client Secret provided.

  Note

  These values are not recoverable once the dialog is closed.

3. Logging in with the API

• Install via pip:

$ pip install featrixclient     # or pip3 install featrixclient

• Instantiate a Featrix object in Python to authenticate and connect to the API.

import featrixclient as ft                                        # pip3 install featrixclient

FEATRIX_CLIENT_ID = os.environ.get('FEATRIX_CLIENT_ID')           # Put your secrets in a secrets manager!
FEATRIX_CLIENT_SECRET = os.environ.get('FEATRIX_CLIENT_SECRET')

featrix = ft.new_client(client_id=FEATRIX_CLIENT_ID, client_secret=FEATRIX_CLIENT_SECRET)

• You can use help() on Python objects to view their docstrings.

Featrix API Overview

The API provides a primary interface, Featrix, and six key objects: FeatrixUpload, FeatrixProject, FeatrixEmbeddingSpace, FeatrixModel, and FeatrixJob.

• `Featrix`: Main entry point for accessing everything in the Featrix environment.

• `FeatrixUpload`: Represents data files uploaded to the system. Contains metadata after processing and enrichment.

• `FeatrixProject`: Manages embedding spaces, associates uploaded files, sets parameters, and links predictive models to projects.

• `FeatrixEmbeddingSpace`: Trained on project data, provides metadata interface for the trained embedding space.

• `FeatrixNeuralFunction`: Represents a predictive model. Trained on embedding spaces and specific datasets.

• `FeatrixJob`: Represents asynchronous tasks like training, providing progress updates.

The API supports scalar predictions, classifications, recommendations, clustering using embedding spaces. You can use our embeddings with popular vector databases for similarity search of your tabular data. You can also mix in embeddings from any LLM model into Featrix and, by default, Featrix uses sentence-transformer models for string embeddings found in your data.

The API integrates seamlessly with Python libraries like Pandas, Matplotlib, Sklearn, Numpy, and PyTorch. For support or enhancements, contact hello@featrix.ai or join our Slack community.

class featrixclient.networkclient.Featrix(url: str = 'https://app.featrix.com', client_id: str | None = None, client_secret: str | None = None, key_file: Path | str = PosixPath('/home/docs/.featrix.key'), allow_unencrypted_http: bool = False)

The Featrix class provides access to all the facilities of Featrix.

debug: bool = False

instance: Featrix = None

__init__(url: str = 'https://app.featrix.com', client_id: str | None = None, client_secret: str | None = None, key_file: Path | str = PosixPath('/home/docs/.featrix.key'), allow_unencrypted_http: bool = False)

Create a Featrix client object.

This requires authentication using API Keys (client ID and secret) from the Featrix UI at https://app.featrix.com. The credentials can be provided in one of three ways:

1. As client_id and client_secret arguments.

2. Set in the environment variables FEATRIX_CLIENT_ID and FEATRIX_CLIENT_SECRET.

3. Stored in ${HOME}/.featrix.key (or a specified file via key_file), with the format:

FEATRIX_CLIENT_ID=xxxxxxxxxx FEATRIX_CLIENT_SECRET=xxxxxxxxxx

To generate an API Key, register and log in at https://app.featrix.com/. Under your Profile menu, select “Manage API Keys.”

Parameters:

• url (str) – URL of the Featrix server (default: https://app.featrix.com/).

• client_id (str | None) – API Key client ID.

• client_secret (str | None) – API Key client secret.

• key_file (str | Path | None) – File containing API Key credentials.

• allow_unencrypted_http (bool) – Allow non-HTTPS connections (for development).

Returns:

A Featrix object for accessing neural functions and performing predictive AI queries.

static get_instance() → Featrix

projects() → List[FeatrixProject]

Return a list of all projects in your account.

Each project includes its name, associated data sets (associated_uploads), any mappings between data sets (mappings), and columns ignored by the project (ignore_cols).

Returns:

A list of projects.

Return type:

List[FeatrixProject]

get_project_by_id(project_id: str | PydanticObjectId) → FeatrixProject | None

Find a project in the projects cache by its id (FeatrixProject.id)

Returns:

The project object found in the cache

Return type:

FeatrixProject

get_project_by_name(name: str) → FeatrixProject | List[FeatrixProject] | None

Find a project in the projects cache by its name (FeatrixProject.name)

Returns:

The project object found in the cache

Return type:

FeatrixProject

create_project(name: str | None = None, user_meta: Dict | None = None, tags: List[str] | None = None) → FeatrixProject

Create a new project and set it as the current project.

Parameters:

• name (str | None) – Optional project name; auto-named if not provided.

• user_meta (dict | None) – Optional metadata to associate with the project.

• tags (list | None) – Optional tags to associate with the project.

Returns:

The newly created project object.

Return type:

FeatrixProject

get_uploads() → None

Get all the FeatrixUpload entries that describe files the user has uploaded to the Featrix system.

get_upload(upload_id: str = None, filename: str = None, reload: bool = True) → FeatrixUpload

Return the FeatrixUpload object (FeatrixUpload) for the given upload id or filename.

Parameters:

• upload_id (str) – Upload id of an upload to find in the library (FeatrixUpload.id)

• filename (str) – the filename to use to locate an upload in the library (FeatrixUpload.filename)

• reload (bool) – if the upload isn’t here, try to reload the library

Returns:

FeatrixUpload for the given id or filename, otherwise it will raise a FeatrixException.

upload_files(uploads: List[DataFrame | str | Path] | DataFrame | str | Path, associate: FeatrixProject | None = None, labels: List[str | None] | None = None) → List[FeatrixUpload]

Upload files or DataFrames to the Featrix system, optionally associating them with a project.

Parameters:

• uploads (list) – List of filenames (str or pathlib.Path) or pandas.DataFrame objects to upload.

• associate (FeatrixProject | None) – Optional project to associate with the uploads.

• labels (list | None) – Optional labels for the uploads; defaults to filenames or auto-generated labels for DataFrames.

• upload – If uploads is not used, takes a single upload.

Returns:

The list of created FeatrixUpload objects.

Return type:

List[FeatrixUpload]

upload_file(upload: DataFrame | str | Path, associate: FeatrixProject | None = None, label: str | None = None) → FeatrixUpload

Create a new upload in your library from a DataFrame or CSV file.

This creates a FeatrixUpload in your library, uploads the data to Featrix, and starts a post-upload analysis (typically completed within 60 seconds). The upload will be accessible via get_upload.

If associate is True, the upload is associated with the current project. If associate is a FeatrixProject, it will be associated with that specific project.

Parameters:

• upload (pd.DataFrame | str | Path) – The data to upload, either as a DataFrame or a CSV file path.

• associate (FeatrixProject | bool | None) – Optionally associate the upload with a project.

• label (str | None) – Optional label for the upload; used as filename if provided with a DataFrame.

Returns:

The created upload object.

Return type:

FeatrixUpload

get_neural_function(neural_function_id, in_project: FeatrixProject | str | None = None) → FeatrixNeuralFunction

Retrieve a neural function object by its ID, optionally within a specific project.

Parameters:

• neural_function_id (str) – The ID of the neural function to retrieve.

• project (FeatrixProject | None) – Optional project to search within; otherwise, all projects are searched.

Returns:

The retrieved neural function object.

Return type:

FeatrixNeuralFunction

get_model(neural_function_id, in_project: FeatrixProject | str | None = None) → FeatrixNeuralFunction

Alias for get_neural_function

check_updates(**kwargs)

class featrixclient.FeatrixUpload(*, id: PydanticObjectId = None, created_by: PydanticObjectId | str | None = None, created_at: datetime = None, updated_at: datetime = None, filename: str, pathname: str, organization_id: PydanticObjectId, num_rows: int = -1, num_cols: int = -1, column_names: List[str] = None, enriched_column_names: List[str] = None, file_hash: str, load_errors: Dict = None, post_processing_job_id: PydanticObjectId | None = None, sample_data: List[Dict[str, Any]] = None, sample_rows: int = 0, sample_percent: float = 1.0, user_meta: Dict[str, Any] = None, df: object | None = None, processing_error_list: List[str] | None = None, processing_start_time: datetime | None = None, processing_end_time: datetime | None = None, possible_id_columns: List[str] | None = None, detected_column_types: Dict[str, str] | None = None, ready_for_training: bool = False, col_histograms: Dict | None = None, col_unique_counts: Dict[str, int] | None = None, col_nonnull_counts: Dict[str, int] | None = None, col_likely_positive_value: Dict[str, Any] | None = None, smart_enrichment_config: Dict[str, bool] | None = None, smart_enrichment_results: Dict | None = None, smart_enrichment_last_start_time: datetime | None = None, smart_enrichment_last_end_time: datetime | None = None, test_split_ratio: float = 0.2, train_split_ratio: float = 0.6, validation_split_ratio: float = 0.2, test_split_file_hash: str | None = None, train_split_file_hash: str | None = None, validation_split_file_hash: str | None = None, ignore_cols: List[str] | None = None, drop_duplicates: bool = True, debug_detectors_raw: Dict | None = None)

Represents a file upload to the Featrix server for training, including metadata, analysis results, and possible enrichments.

Retrieve an upload by ID with .by_id(), and refresh an existing upload object with .refresh() if it might have changed.

property fc

refresh()

get_jobs(active: bool = True) → List['FeatrixJob']

Return a list of jobs associated with this upload.

By default, only active jobs are returned. Use the arguments to filter results.

Parameters:

• active (bool) – If True, return only active jobs.

• training (bool) – If True, return only training jobs.

Returns:

The list of jobs associated with this upload.

Return type:

List[FeatrixJob]

classmethod new(fc: Any, filename: str | Path, user_meta: Dict | None = None) → FeatrixUpload

Create a new FeatrixUpload object and upload the file to the server.

classmethod all(fc: Any) → List[FeatrixUpload]

Get all uploads on the server

Parameters:

fc – Featrix class instance

Returns:

List of all uploads on the server

Return type:

List[FeatrixUpload]

classmethod by_id(upload_id: str | PydanticObjectId, fc: 'Featrix' | None = None) → FeatrixUpload

Get a specific upload by its id

Parameters:

• upload_id – str: the upload id

• fc – Featrix class instance

Returns:

The upload if it exists, otherwise None

Return type:

FeatrixUpload

classmethod by_hash(hash_id: str, fc: 'Featrix' | None = None) → FeatrixUpload

Get a specific upload by its hash

Parameters:

• hash_id – str: the hash id

• fc – Featrix class instance

Returns:

The upload if it exists, otherwise None

Return type:

FeatrixUpload

delete() → FeatrixUpload

Delete the upload from the server

Returns:

The upload that was deleted

Return type:

FeatrixUpload

jobs()

Get the jobs associated with this upload

Returns:

List of jobs associated with this upload

Return type:

List[FeatrixJob]

class featrixclient.FeatrixProject(*, id: PydanticObjectId = None, created_by: PydanticObjectId | str | None = None, created_at: datetime = None, updated_at: datetime = None, has_haystack: bool = False, has_feeds: bool = False, gui_color: str | None = '#cccccc', name: str, organization_id: PydanticObjectId, tags: List[str] = None, type: ProjectType = ProjectType.SDK, associated_uploads: List[UploadAssociation] = None, embedding_space_ids: List[PydanticObjectId] = None, ignore_cols: List[str] = None, focus_cols: List[str] = None, encoder_overrides: List[dict] | None = None, mappings: list[ProjectTableMapping] = [], user_meta: Dict[str, Any] = None, readme_text: str | None = None, banner_text: str | None = None, type_overrides: List | None = None, haystack_config: dict | None = None, haystack_results: list | None = None, haystack_ad_hoc_results: list | None = None, **extra_data: Any)

Represents a project in Featrix, organizing embedding spaces and neural functions. A project allows setting default embedding space settings and associating data files for training.

You can typically use project references returned by various Featrix methods (e.g., create_project). However, this class provides methods for all project-related operations.

Retrieve a project by ID with by_id(), and refresh an existing project reference with .refresh() to get the latest version.

The .ready() method checks if the project is ready for model creation/training, indicating if associated data files have been processed. If wait_for_completion=True, it will block with status messages until all files are ready.

property fc

refresh()

classmethod new(fc: Any, name: str | None = None, project_type: ProjectType = ProjectType.SDK, user_meta: Dict | None = None, tags: List[str] | None = None)

Load or create a project. If project_id is provided, an existing project is retrieved. Otherwise, the project is looked up by name, and if it doesn’t exist, a new one is created.

Parameters:

• fc (FeatrixClient) – The Featrix client.

• name (str | None) – Optional name of the project to look up or create.

• project_type (ProjectType) – The type of project, defaulting to SDK.

• user_meta (dict | None) – Optional metadata for a new project.

• tags (list | None) – Optional list of tags to add to the project.

classmethod all(fc: 'Featrix' | None = None) → List[FeatrixProject]

Retrieve all known projects from the Featrix server.

Parameters:

fc – Featrix class

Returns:

List of FeatrixProject instances

classmethod by_id(project_id, fc: 'Featrix' | None = None) → FeatrixProject

Retrieve a project from the Featrix server by its id (FeatrixProject.id)

Parameters:

• project_id – str - the id of the project to retrieve

• fc – Featrix class

Returns:

FeatrixProject instance

ready(wait_for_completion: bool = False) → bool

Check to see if all of the data files that are contained in this project are ready to be used for training.

Parameters:

wait_for_completion – bool - if True, will wait for the data files to be ready before returning

Returns:

bool - True if all data files are ready for training, False otherwise

create_embedding_space(name: str | None = None, wait_for_completion: bool = True, encoder: Dict | None = None, ignore_cols: List[str] | str | None = None, focus_cols: List[str] | str | None = None, **kwargs) → FeatrixEmbeddingSpace

Create a new embedding space in a specified project.

Data can include strings and missing values; no need for cleaning. If wait_for_completion is set to True, the process is synchronous with periodic status updates. The training will complete even if interrupted, and the status can be checked later.

This returns a tuple with the FeatrixEmbeddingSpace object and the FeatrixJob object responsible for the training. The FeatrixEmbeddingSpace.training_state shows the embedding space’s state, while the Job provides detailed status information.

Parameters:

• project (FeatrixProject | str | None) – The project to use; a new project is created if not provided.

• name (str) – Name of the embedding space.

• wait_for_completion (bool) – Run synchronously with status updates.

• encoder (dict | None) – Optional encoder overrides for the embedding space.

• ignore_cols (list | str | None) – Columns to ignore in training (list or comma-separated string).

• focus_cols (list | str | None) – Columns to focus on in training (list or comma-separated string).

• **kwargs – Additional arguments for ESCreateArgs, e.g., rows=1000.

Exceptions:

FeatrixNotReadyException: Thrown if the project data files are missing or not finished processing.

Returns:

The embedding space and associated training job.

Return type:

FeatrixEmbeddingSpace

save() → FeatrixProject

Save the project to the Featrix server including anything changed (such as meta or the name).

Returns:

FeatrixProject instance

jobs() → List[FeatrixJob]

Retrieve the jobs associated with this project. If the jobs have already been retrieved, they will be returned from the cache unless force is True.

Returns:

List of FeatrixJob instances

job_by_id(job_id: str | PydanticObjectId) → FeatrixJob

Get a job by its Job id, possibly refreshing the cache if force is True.

Parameters:

job_id – str - the id of the job to retrieve

Returns:

FeatrixJob instance

embedding_spaces() → List[FeatrixEmbeddingSpace]

Retrieve the embedding spaces associated with this project. If the embedding spaces have already been retrieved, they will be returned from the cache unless force is True.

Returns:

List of FeatrixEmbeddingSpace instances

embedding_space_by_id(embedding_space_id: str | PydanticObjectId) → FeatrixEmbeddingSpace

Get an embedding space by its id, possibly refreshing the cache if force is True.

Parameters:

embedding_space_id – str - the id of the embedding space to retrieve

Returns:

FeatrixEmbeddingSpace instance

neural_functions(embedding_space: FeatrixEmbeddingSpace = None)

This is a convenience function that allows the user to get all the neural_functions for all their embeddings directly from the project (possibly pulling data from the server)

Parameters:

embedding_space – Get the models for the referenced embedding space, or if none, all of them

Returns:

List of FeatrixNeuralFunction instances across this project’s embedding spaces

neural_function_by_id(ident: str) → FeatrixNeuralFunction

Find a model by its id across all embedding spaces in this project. The stale timeout tells us how old to allow the cache to be before refreshing it – -1 can be used to force it always.

Parameters:

ident – str - the id of the model to find

Returns:

FeatrixNeuralFunction instance or None if not found

fields()

Retrieve all fields that are in data files associated with this project.

associate(upload: FeatrixUpload, label: str | None = None, sample_row_count: int = 0, sample_percentage: float = 1.0, drop_duplicates: bool = True)

Associate a FeatrixUpload with this project.

Parameters:

• upload – FeatrixUpload - the upload to associate

• label – str - optional label to give the association

• sample_row_count – int - number of rows to sample

• sample_percentage – float - percentage of rows to sample

• drop_duplicates – bool - whether to drop duplicates

Returns:

FeatrixProject updated instance

add_mapping(source_label, target_label, *args)

Add a mapping between fields in the source and target data files associated with this project.

Parameters:

• source_label – str - the label of the source data file

• target_label – str - the label of the target data file

• *args – tuple - each tuple should be a pair of fields to map

Returns:

FeatrixProject updated instance

add_ignore_columns(columns: List[str] | str, *args)

Add columns to ignore when training the embedding space.

Parameters:

• columns – List[str] | str - the columns to ignore or a column name

• *args – additional column names – allows calling .add_ignore_columns(“col1”, “col2”, “col3”) or with a list

Returns:

FeatrixProject updated instance

delete()

Delete the project from the Featrix server. This will remove all associated data files, embedding spaces, neural functions, etc. Proceed with extreme caution.

Returns:

ProjectDeleteResponse

class featrixclient.FeatrixEmbeddingSpace(*, id: PydanticObjectId = None, created_by: PydanticObjectId | str | None = None, created_at: datetime = None, updated_at: datetime = None, project_id: PydanticObjectId | None = None, name: str, organization_id: PydanticObjectId, system_meta: Dict = None, user_meta: Dict = None, es_neural_attrs: Dict | None = None, training_history: List[TrainingInfo] = None, config_split_columns: List[Dict] | None = None, notes: List[str] | None = None, dimension: int = 64, training_state: TrainingState = TrainingState.UNTRAINED, training_credits_budgeted: float = 0.0, training_credits_actual: float = 0.0, **extra_data: Any)

Represents a multimodal embedding space.

This lets you create multimodal embeddings for assorted tabular data sources in a single trained embedding space, building a foundational model on your data in such a way that you can query the entire data by using partial information that maps into as little as one of your original data sources, or you can leverage partial information spanning multiple data sources.

You create embedding spaces in a project, and the training uses data files you have associated with the project in the training. You can use a subset of the data, ignore columns, or change mappings to rapidly experiment with models using this call.

This function will use auto-join to find the linkage and corresponding overlapping mutual information between data files that have been loaded. Then a new embedding space is trained with the following columns:

• Base data file: all columns (unless ignored in the ignore_cols parameter)

• 2nd data file: all columns, renamed to <2nd data file label> + “_” + <original_col_name>

  However, the columns used for linking will not be present, as they will get their mapped names in the base data file.

  To ignore a column in the 2nd data file, specify the name in the transformed format.

• 3rd data file: same as 2nd data file.

This trains the embedding space in the following manner:

Let’s imagine the 2nd_file_col1 and 3rd_file_col2 are the linkage to col1 in the base data set. The training space will effectively be a sparse matrix:

col1                    col2          col3        2nd_file_col2       2nd_file_col3       3rd_file_col2
values from base data.....................        [nulls]                                 [nulls]
.
.
.
2nd_file_col1 in col1   [nulls]                   values from 2nd file................... [nulls]
.                       .                         .
.                       .                         .
3rd_file_col1 in col2   [nulls]                   [nulls]                                 values from 3rd file
.                       .                         .                                       .
.                       .                         .                                       .
.                       .                         .                                       .

property fc

refresh()

ready()

static create_args(project_id: str, name: str, **kwargs) → ESCreateArgs

Create the arguments for an embedding space creation call with the parameters passed in.

Returns an ESCreateArgs object that can be passed to the API for creating an embedding space.

get_jobs(active: bool = True, training: bool = True) → List['FeatrixJob']

Return a list of jobs that are associated with this model. By default it will only return active (not finished) training jobs, but the caller can use the two arguments to control this.

Parameters:

• active – bool: If True, only return active jobs

• training – bool: If True, only return training jobs

Returns:

The list of jobs associated with this model

Return type:

List[FeatrixJob]

classmethod new_embedding_space(fc: Any, project: 'FeatrixProject' | str, name: str | None = None, wait_for_completion: bool = True, encoding: Dict | None = None, focus_cols: List[str] | str | None = None, ignore_cols: List[str] | str | None = None, **kwargs) → FeatrixEmbeddingSpace

This creates a chained-job to do training first on an embedding space, and then on the predictive model within that embedding space. It returns a tuple which is the two jobs (the first job for the embedding space training and the second for the predictive model training).

classmethod all(fc) → List[FeatrixEmbeddingSpace]

Return a list of all embedding spaces defined by the user (regardless of project)

Parameters:

fc – Featrix class instance

Returns:

List of FeatrixEmbeddingSpace objects

classmethod by_id(es_id: PydanticObjectId | str, fc) → FeatrixEmbeddingSpace

Retrieve an embedding space by its ID from the server

Parameters:

• es_id – The ID of the embedding space

• fc – Featrix class instance

Returns:

FeatrixEmbeddingSpace object

training_jobs() → List['FeatrixJob']

Fetch all training jobs for this Embedding Space, returning them as a list in order they were executed

neural_functions(lambda_filter=None) → List[FeatrixNeuralFunction]

Retrieve all neural functions for this embedding space.

neural_function_by_id(model_id: str | PydanticObjectId) → FeatrixNeuralFunction

Get a neural function by its id.

Parameters:

model_id – The ID of the model to retrieve

Returns:

FeatrixNeuralFunction object

create_neural_function(target_field: str, target_field_type: str | None = 'auto', wait_for_completion: bool = True, encoder: Dict | None = None, **kwargs) → FeatrixNeuralFunction

Creates a new neural function – a predictive model.

If the wait_for_completion flag is set, this will be synchronous and print periodic messages to the console or notebook cell. Note that the jobs are enqueued and running so if the caller is interrupted, reset or crashes, the training will still complete.

The caller, in the case where they do not wait for completion, can follow the progress via the jobs objects.

nf_training_job = create_neural_function("field_name")
if nf_training_job.completed is False:
    nf_training_job = nf_training_job.check()
    print(nf_training_job.incremental_status)

Parameters:

• target_fields – the field name(s) to target in the prediction

• files – a list of dataframes or paths to files to upload and associate with the project (optional - if you already associated files with the project, this is redundant)

• wait_for_completion (bool) – make this synchronous, printing out status messages while waiting for the training to complete

• encoder – Optional dictionary of encoder overrides to use for the embedding space

• ignore_cols – Optional list of columns to ignore in the training (a string of comma separated column names or a list of strings)

• focus_cols – Optional list of columns to focus on in the training (a string of comma separated column names or a list of strings)

• ModelCreateArgs (**kwargs -- any other fields to) – create_embedding_space(project, name, credits, files, wait_for_completion, rows=1000)

Returns:

FeatrixNeuralFunction - the Featrix neural function.

delete() → FeatrixEmbeddingSpace

Delete this embedding space off the server

embed_record(upload: DataFrame | str | Path) → List[Dict]

Use this trained embedding space to create embeddings for rows of data. The rows may be in or out of the training set. You can use the resulting vector embeddings to train your own models outside of Featrix, to cluster data items with the relationships that created the embedding transformation on the training data–this is often extremely powerful.

You can also use these embeddings to chain together composite Featrix neural functions.

class featrixclient.FeatrixNeuralFunction(*, id: PydanticObjectId = None, created_by: PydanticObjectId | str | None = None, created_at: datetime = None, updated_at: datetime = None, name: str, organization_id: PydanticObjectId, project_id: PydanticObjectId | None = None, embedding_space_id: PydanticObjectId, associated_uploads: List[UploadAssociation] = None, target_columns: List[str] | None = None, training_rows: int = 0, training_input_columns: List[str] | None = None, training_num_uniques: int | None = None, training_num_not_nulls: int | None = None, training_target_histogram: Dict | None = None, training_metrics: Dict | None = None, learning_rate: float = 0.0001, epochs: int = 0, model_size: str = 'small', target_type: str | None = None, mlp_predictor: str | None = None, job_id: PydanticObjectId | None = None, training_state: TrainingState = TrainingState.UNTRAINED, training_credits_budgeted: float = 0.0, training_credits_actual: float = 0.0, user_meta: Dict[str, Any] = None, **extra_data: Any)

Represents a neural function (predictive model) trained against an embedding space for predicting a specific feature or field.

Create and train a new neural function with .new_neural_function(). Retrieve an existing neural function by its ID with .by_id(), and ensure you have the latest version of the model using .refresh():

nf = FeatrixNeuralFunction.by_id(“5f7b1b1b1b1b1b1b1b1b1b”) nf = nf.refresh() # Update after training completes

static create_args(project_id: str, embedding_space_id: str, target_field: str, target_field_type: str, encoder, **kwargs) → ModelCreateArgs

Create the arguments for creating a model. This is a helper function to make it easier to create a ModelCreateArgs

classmethod by_id(model_id: str | PydanticObjectId, fc: Any) → FeatrixNeuralFunction

Get a predictive model by its id.

Returns:

The model if it exists, otherwise None.

Return type:

FeatrixNeuralFunction

classmethod from_job(job: FeatrixJob, fc: 'Featrix' | None = None) → FeatrixNeuralFunction

Given a FeatrixJob, retrieve the predictive model that is referenced by the job.

Parameters:

job – FeatrixJob: The job that references the model – must have model_id set

Returns:

The model if it exists, otherwise None.

Return type:

FeatrixNeuralFunction

property fc

refresh()

ready()

get_jobs(active: bool = True, training: bool = True) → List[FeatrixJob]

Return a list of jobs associated with this model.

By default, only active (unfinished) training jobs are returned. Use the arguments to filter results.

Parameters:

• active (bool) – If True, return only active jobs.

• training (bool) – If True, return only training jobs.

Returns:

The list of jobs associated with this model.

Return type:

List[FeatrixJob]

predict(query: Dict | List[Dict] | DataFrame) → FeatrixPrediction

Predict a probability distribution on a given model in a embedding space.

Query can be a list of dictionaries or a dictionary for a single query.

Parameters:

query (dict, [dict], or pd.DataFrame) – Either a single parameter or a list of parameters. { col1: <value> }, { col2: <value> }

Return type:

A dictionary of values of the model’s target_column and the probability of each of those values occurring.

classmethod new_neural_function(fc: Any, target_field: str, embedding_space: FeatrixEmbeddingSpace, project: FeatrixProject, target_field_type: str | None = 'auto', encoder: Dict | None = None, wait_for_completion: bool = True, **kwargs) → FeatrixNeuralFunction

Create a neural function. Generally you would use FeatrixEmbeddingSpace.create_neural_function(), which calls this.

class featrixclient.FeatrixJob(*, id: PydanticObjectId = None, created_by: PydanticObjectId | str | None = None, created_at: datetime = None, updated_at: datetime = None, organization_id: PydanticObjectId, job_type: JobType, readonly_object: bool = False, project_id: PydanticObjectId | None = None, embedding_space_id: PydanticObjectId | None = None, model_id: PydanticObjectId | None = None, upload_ids: List[PydanticObjectId] | None = None, finished: bool = False, error: bool = False, message: str | None = None, error_msg: str | None = None, error_details: List[str] | None = None, error_time: datetime | None = None, exception: List[str] | None = None, warnings: List[str] | None = None, start_time: datetime | None = None, end_time: datetime | None = None, celery_id: str | None = None, changed_ids: Dict[str, PydanticObjectId | List[PydanticObjectId]] | None = None, finished_stats: JobUsageStats | None = None, request_args: Dict | None = None, incremental_status: JobIncrementalStatus | None = None, last_updated: datetime = None, results: Dict | List | None = None, chained_job_id: PydanticObjectId | None = None, working_directory: str | None = None, working_host: str | None = None, incident: str | int | None = None, system_meta: Dict | None = None, auto_launch: bool | None = None, required_job_id: PydanticObjectId | None = None, parent_job_id: PydanticObjectId | None = None, **extra_data: Any)

Represents a job running on a Featrix cluster.

Key Fields:

• job.finishedbool

  True if the job is finished.

• job.errorbool

  True if the job encountered an error.

• job.incremental_statusJobStatus

  Current status, including job.incremental_status.message for progress updates.

Methods:

• by_id(job_id, fc)FeatrixJob

  Retrieve a job by ID using a FeatrixClient instance.

• refresh()FeatrixJob

  Update the job with the latest status from the server.

• wait_for_completion()FeatrixJob

  Blocks until the job completes, printing status updates.

Related Methods:

• by_project, by_embedding_space, by_model, by_upload

  Retrieve jobs related to specific objects like projects, embedding spaces, models, and uploads.

classmethod by_id(job_id: str | PydanticObjectId, fc: 'Featrix' | None = None) → FeatrixJob

Retrieve a job by its job ID from the server

Parameters:

• job_id – str: the job ID to retrieve

• fc – Featrix: the Featrix class that is making the request

Returns:

FeatrixJob new instance of job

property fc

refresh()

check()

classmethod by_neural_function(model: FeatrixNeuralFunction) → List['FeatrixJob']

classmethod by_embedding_space(embedding_space: FeatrixEmbeddingSpace) → List['FeatrixJob']

classmethod by_project(project: FeatrixProject) → List['FeatrixJob']

classmethod by_upload(upload: FeatrixUpload) → List['FeatrixJob']

static wait_for_jobs(fc: Any, jobs: List[FeatrixJob], msg: str = 'Waiting for jobs: ', cycle: int = 5) → List[FeatrixJob]

Given a list of FeatrixJob’s, wait for all of them to be completed, periodically updating their status on the console.

Parameters:

• fc – Featrix: the Featrix class that is making the request

• jobs – List[FeatrixJob]: the list of jobs to wait for

• msg – str: the message to display on the console

• cycle – int: the number of seconds to wait between updates

Returns:

the updated list of jobs that have been completed

Return type:

List[FeatrixJob]

wait_for_completion(message: str | None = None) → FeatrixJob

classmethod check_guardrails(fc: Any, model: FeatrixNeuralFunction, query: List[Dict] | Dict, issues_only: bool = False) → FeatrixJob

Kick off a Check Guardrails on a query or list of queries.

Parameters:

• fc – Featrix: the Featrix class that is making the request

• model – FeatrixNeuralFunction: the model to check guardrails on

• query – List[Dict] | Dict: the query or list of queries to check

• issues_only – bool: if True, only return the issues, not the full results

Returns:

the job that is running the guardrails check

Return type:

FeatrixJob

classmethod from_job_dispatch(jd: JobDispatch, fc) → FeatrixJob