> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine State Lens

The **Machine State Lens** classifies the operational state of a machine using its sensor measurements. It can distinguish between normal operation, stressed conditions, and a variety of anomaly or failure modes (such as overheating, mechanical wear, or misalignment). These classifications support common engineering tasks like monitoring machine health, diagnosing issues, and optimizing performance.

Developers can **configure the lens’s focus** by supplying a small number of labeled examples that represent the machine states they want to detect. Because abnormal-state data is often limited, the lens supports **one-shot and few-shot classification**, allowing it to generalize to new machines and new state categories without retraining or fine-tuning. This makes it suitable for deployments where labeled data is sparse but rapid adaptation is required.

## Configuration Example

Here is an example configuration for the Machine State lens:

```yaml theme={"system"}
lens_config:
  model_pipeline:
    - processor_name: lens_timeseries_state_processor
      processor_config: {}
  model_parameters:
    model_name: OmegaEncoder
    model_version: OmegaEncoder::omega_embeddings_01
    normalize_input: true
    buffer_size: 1024
    csv_configs:
      timestamp_column: timestamp
      data_columns:
        - a1
        - a2
        - a3
        - a4
      window_size: 1024
      step_size: 1024
    knn_configs:
      n_neighbors: 5
      metric: manhattan
      weights: distance
      algorithm: ball_tree
      normalize_embeddings: false
    input_n_shot:
      healthy: healthy.csv
      broken: broken.csv
    min_replicas: 1
    max_replicas: 1
  input_streams:
    - stream_type: csv_file_reader
      stream_config:
        file_id: data.csv
        window_size: 1024
        step_size: 1024
        loop_recording: false
        output_format: ""
  output_streams:
    - stream_type: server_sent_events_writer
```

## Running the Machine State Lens

Try the Machine State Lens in the command line, or through the no-code workbench with the following [example files](https://drive.google.com/drive/folders/1IGD_0rLbJmyekJxO2OqpF5lgqdAqUklo?usp=drive_link).

<Card title="Machine State CLI Example" icon="terminal" href="/code-examples/command-line-demos/machine-state/machine-state">
  Step-by-step guide to running the Machine State lens from the command line
</Card>

<Card title="Machine State Workbench Example" icon="sparkles" href="https://docs.archetypeai.app/developer-console/workbench/machine-state">
  Step-by-step guide to running the Machine State Lens in a no-code environment
</Card>

## Lens Input

The Lens input consists of time-varying sensor measurements representing physical parameters of a machine over time. These measurements can be provided either as a live stream from one or more sensors or as a prerecorded data file.

### General Requirements

* The sampling rate should be fixed and constant over the lens session: monotonically increasing, fixed intervals.
* Each variate should have the same sampling rate and sample time points.
* The maximum supported number of variates (channels) is 4.
* The data may contain NaNs or Infs. However the lens will output an INVALID\_STATE identifier at the corresponding time point(s).

### Using Pre-recorded .CSV files

* The supported file format is CSV.
* The CSV file should have a column for each variate. The variate (column) names should be specified in the header row.
* If the number of variates in the CSV file exceeds the maximum supported, the user should specify a list of variate names to be used by the lens. If no list is provided, then the lens will default to the first four non-timestamp columns.
* Each row of the CSV file should contain the data for one time point.
* The sensor measurements should be formatted as plain-text numeric values.
* The CSV file should contain a column called "timestamp" containing the timestamp for each time point. The supported timestamp formats are ISO 8601 and Unix.

### For Live Sensor Streams

* One sensor stream per session is supported. This stream should contain the data for all sensor variates (up to 4).
* The supported sensor measurement data types are floats and integers.
* The maximum number of time points per sensor stream packet is 1024. The number of time points per sensor stream packet can vary over the course of a session.
* Each sensor stream packet should contain the name of each variate as a key and the variate measurement data in an array as the associated value.
* Each sensor stream packet should contain a key called "timestamp" and the timestamps of the packet data in an array as the associated value. The supported timestamp formats are ISO 8601 and Unix.

### Working with Data Streams

Developers can stream generic timeseries data from pre-recorded CSV files into a Lens by connecting a *CSV File Reader* data connector to the [**input data stream**](https://docs.archetypeai.app/core-concepts/introduction/introduction#lens-data-streams) of a Lens.

See the following data streams on how to hook up your sensor data:

<CardGroup cols={2}>
  <Card title="CSV File Reader" icon="eye" href="/core-concepts/streams/readers/csv_reader">
    Reads sensor data from a CSV file.
  </Card>
</CardGroup>

## Lens Parameters

**Basic Parameters**

* **Input N Shot Examples:** To produce meaningful state outputs for a specific use case, the Lens must be focused using labeled examples of sensor data for each state of interest. Each example is provided to the Lens as a CSV file.
  * The specifications of the focus data file should match that of the incoming data stream, i.e. the sampling rate, variates, data formats, and timestamp formats should be the same.
  * At least one example must be provided for each possible state of the machine.
* **Window Size:** Number of rows analyzed together. (Default is 1024)
  * **Smaller values** (e.g., 256): more frequent predictions, less context
  * **Larger values** (e.g., 2048): fewer predictions, more context per prediction
* **Step Size:** How many rows to move forward between predictions (Default is 1024).
* **CSV Configuration:** Configuration settings for csv data processing. The goal is to make sure the formatting of your CSV file is compatible with the lens.
  * **Timestamp Column:** The CSV column containing time information. Used to order and label predictions.
  * **Data Columns:** Which sensor/data columns to analyze. Update this array to match your CSV structure.

**Advanced Parameters**

* **Buffer size:** Number of time points to keep in the buffer for each variate
* **Max Replicas:** Maximum number of model replicas allowed for the Lens
* **Min Replicas:** Minimum number of model replicas to maintain for the Lens

## Lens Outputs

The output of the Lens will be a continuous timestamped stream of the identified machine state. Like all Lenses, the Machine State lens outputs a continuous stream of [Events](/core-concepts/streams/events/overview). A developer can connect one-or-more output streams from a Lens to allow them to consume the events.