# Sloan / Demos Documentation – TypeScript

## Included Files
1. sloan/demos/context.mdx
2. sloan/demos/egress.mdx
3. sloan/demos/ingest.mdx
4. sloan/demos/mvs.mdx

## Context Demo -- Aircraft Metrics Definition

Source: sloan/demos/context.mdx

Learn how to use Sloan's context management to build knowledge-driven data applications

# Aircraft Metrics Definition

## Airspeed Metrics

**Ground Speed vs True Airspeed**: Ground speed (`gs`) represents the aircraft's speed relative to the ground, while true airspeed (`tas`) accounts for air density and temperature conditions. True airspeed calculation requires outside air temperature (`oat`) and pressure altitude data not currently available in our model.

**Indicated Airspeed (IAS)**: The airspeed reading from the aircraft's pitot-static system (`ias`), which differs from true airspeed based on altitude and atmospheric conditions. This metric requires direct airspeed sensor data not present in our current ADS-B feed.

## Climb/Descent Performance Metrics

**Vertical Speed**: Calculated using `baro_rate` (barometric rate) and `geom_rate` (geometric rate) to determine climb or descent performance. Positive values indicate climb, negative values indicate descent.

**Climb Efficiency**: Ratio of altitude gained to ground distance covered, calculated using altitude change (`alt_baro` or `alt_geom`) and position changes (`lat`, `lon`).

## Flight Phase Detection Metrics

**Takeoff Phase**: Identified by rapid altitude gain (`alt_baro` increasing) combined with increasing ground speed (`gs`) and high climb rate (`baro_rate` > 500 ft/min).

**Cruise Phase**: Characterized by stable altitude (minimal `baro_rate`), consistent ground speed (`gs`), and straight track (`track` changes < 5°).

**Approach Phase**: Detected by decreasing altitude (`baro_rate` < -300 ft/min), decreasing ground speed, and altitude below typical cruise levels.

**Landing Phase**: Final approach with very low altitude (`alt_baro` < 1000 ft), decreasing speed, and stable track toward runway.

## Signal Quality Metrics 

**Signal Strength**: Direct measurement using `rssi` (Received Signal Strength Indicator) to assess reception quality.

**Data Freshness**: Calculated using `seen` (seconds since last message) and `seen_pos` (seconds since last position update) to determine data reliability.

**Message Frequency**: Messages per minute calculated from `messages` count and time window to assess tracking consistency.

## Position Accuracy Metrics

**Navigation Accuracy**: Composite score using `nic` (Navigation Integrity Category), `nac_p` (Navigation Accuracy Category - Position), and `nac_v` (Navigation Accuracy Category - Velocity) to determine positional reliability.

**Surveillance Accuracy**: Assessment using `sil` (Surveillance Integrity Level) and `sda` (System Design Assurance) to evaluate overall tracking quality.

## Flight Efficiency Metrics 

**Great Circle Deviation**: Comparison of actual flight path (derived from sequential `lat`, `lon` coordinates) against the shortest great circle distance between origin and destination.

**Altitude Optimization**: Analysis of altitude profile against optimal flight levels for given aircraft type and distance.

**Speed Consistency**: Variance in ground speed (`gs`) throughout different flight phases to assess flight smoothness.

**Fuel Efficiency**: Calculated using fuel flow rate (`fuel_flow`) and ground speed to determine nautical miles per gallon. Requires engine performance data not available in our current dataset.

## Environmental & Weather Metrics 

**Wind Speed & Direction**: Calculated by comparing true airspeed (`tas`) with ground speed (`gs`) and track changes. Requires true airspeed data and wind vector information (`wind_speed`, `wind_direction`) not present in our model.

**Turbulence Detection**: Identified through rapid changes in altitude (`alt_baro`) and track (`track`) combined with accelerometer data (`vertical_g_force`, `lateral_g_force`) not available in ADS-B transmissions.

**Weather Avoidance**: Analysis of flight path deviations around weather systems using onboard weather radar data (`weather_radar_returns`) and precipitation intensity (`precip_intensity`) not included in our current data model.

## Traffic Density & Separation Metrics

**Aircraft Density**: Count of aircraft within defined geographical boundaries using `lat`, `lon` coordinates and configurable radius.

**Separation Metrics**: Minimum distances between aircraft calculated using position data and altitude differences.

**Airspace Utilization**: Percentage of available airspace occupied by tracked aircraft at different altitude bands.

## Operational Metrics

**Emergency Detection**: Identification of emergency situations using `emergency` codes, `squawk` codes (7500, 7600, 7700), and `alert` flags.

**Autopilot Usage**: Analysis of autopilot engagement using navigation modes (`nav_modes`) and flight path consistency.

**Communication Quality**: Assessment based on transponder performance, message consistency, and data completeness across all available fields.

---

## Egress Demo

Source: sloan/demos/egress.mdx

Learn how to create data egress APIs using Sloan with a step-by-step TypeScript example

# Data Egress

## Create analytics APIs to serve your data

This demo will walk you through using Sloan tools to prompt your way to creating analytics APIs that serve the aircraft telemetry data you've ingested.

[Skip to prompt](#prompt-the-llm-to-create-a-geolocation-api) if you started with the ads-b template.

- **Sloan and Moose CLIs**: [Install them here](/sloan/getting-started/cursor)
- **OS**: macOS or Linux (WSL supported for Windows)
- **Docker Desktop/Engine**: [24.0.0+](https://docs.docker.com/get-started/get-docker/)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Anthropic API Key**: [Get one here](https://docs.anthropic.com/en/docs/initial-setup)
- **Client**: [Cursor](https://www.cursor.com/) 
- **Completed**: [Ingest Demo](/sloan/demos/ingest) (or have data already in your system)

### Start with the ads-b template

```bash filename="Terminal" copy
sloan init egress-demo ads-b
```

```bash filename="Terminal" copy
cd egress-demo
npm install
```

### Run the Moose Dev Server

```bash filename="Terminal" copy
moose dev 
```

### Open the project in Cursor

### Initialize the Sloan MCP

Navigate to `Cursor > Settings > Cursor Settings > Tools and Integrations` then toggle on the `Sloan MCP` tool.

### For best results, set the LLM to `claude-4-sonnet`

Gemini 2.5 and o3 are also reasonably good, but claude-4-sonnet has the most consistent results.

### Prompt the LLM to create a geolocation API

> Can you create an API that returns every aircraft within X miles of Y,Z coordinates.

### Action

The LLM should now use sloan tools to:
1. create the analytics API endpoint that calculates distance and filters aircraft
2. test the API to ensure it's working correctly with the existing aircraft data

You'll know it is succeeding if:
1. the LLM successfully tests the API
2. you can curl the API generated
3. you can see the generated openapi spec in `path/to/your/project/.moose/openapi.yaml`

### Continue this demo with:

* [Creating Materialized Views](/sloan/demos/mvs)

---

## Ingest Demo

Source: sloan/demos/ingest.mdx

Learn how to ingest data using Sloan with a step-by-step TypeScript example

# Ingest

## Ingest data periodically from an API

This demo will walk you through using Sloan tools to prompt your way to ingesting a whole bunch of aircraft telemetry data from adsb.lol.

[Skip to prompt](#prompt-the-llm-to-create-an-ingest) if you started with the ads-b template.

- **Sloan and Moose CLIs**: [Install them here](/sloan/getting-started/cursor)
- **OS**: macOS or Linux (WSL supported for Windows)
- **Docker Desktop/Engine**: [24.0.0+](https://docs.docker.com/get-started/get-docker/)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Anthropic API Key**: [Get one here](https://docs.anthropic.com/en/docs/initial-setup)
- **Client**: [Cursor](https://www.cursor.com/) 

### Create and initialize a new typescript project

```bash filename="Terminal" copy
sloan init ingest-demo typescript-empty
```

```bash filename="Terminal" copy
cd ingest-demo
npm install
```

### Open the project in Cursor

### Run the Moose Dev Servers

```bash filename="Terminal" copy
moose dev 
```

### Initialize the Sloan MCP

Navigate to `Cursor > Settings > Cursor Settings > Tools and Integrations` then toggle on the `Sloan MCP` tool.

### For best results, set the LLM to `claude-4-sonnet`

Gemini 2.5 and o3 are also reasonably good, but claude-4-sonnet has the most consistent results.

### Prompt the LLM to create an ingest

> I want to ingest data from the following aircraft transponder data api every 5 seconds for the purpose of creating a set of visualizations.
> 
> API: @https://api.adsb.lol/v2/mil 
>
> Docs: @https://api.adsb.lol/docs#/v2/v2_mil_v2_mil_get (note, I think the schema here is inaccurate, check out the data before you trust the docs).
> 
> Can you execute on this?

The LLM might do a planning step, in which case, you can ask it to execute on the plan.

> Go for it!

### Action

The LLM should now use sloan tools to:
1. get sample data from the API using a temporary script
2. use that sample to create a schema that's used to create an ingest pipeline (ingest API, Redpanda stream, ClickHouse table)
3. create a Moose managed temporal workflow to periodically ingest the data

You'll know it is succeeding if you see dozens of events per second hit your Moose dev console.

### Continue this demo with:

* [Creating Egress APIs](/sloan/demos/egress)
* [Creating Materialized Views](/sloan/demos/mvs)

---

## Materialized Views Demo

Source: sloan/demos/mvs.mdx

Learn how to create materialized views using Sloan with a step-by-step TypeScript example

# Materialized Views

## Create materialized views to pre-aggregate your data, based on your egress API

This demo will walk you through using Sloan tools to prompt your way to creating materialized views that pre-aggregate the aircraft telemetry data you've ingested.

[Skip to prompt](#prompt-the-llm-to-create-a-materialized-view) if you started with the ads-b template.

- **Sloan and Moose CLIs**: [Install them here](/sloan/getting-started/cursor)
- **OS**: macOS or Linux (WSL supported for Windows)
- **Docker Desktop/Engine**: [24.0.0+](https://docs.docker.com/get-started/get-docker/)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Anthropic API Key**: [Get one here](https://docs.anthropic.com/en/docs/initial-setup)
- **Client**: [Cursor](https://www.cursor.com/) 
- **Completed**: [Ingest Demo](/sloan/demos/ingest) (or have data already in your system)

### Start with the ads-b template

```bash filename="Terminal" copy
sloan init mvs-demo ads-b
```

```bash filename="Terminal" copy
cd mvs-demo
npm install
```

### Run the Moose Dev Server

```bash filename="Terminal" copy
moose dev 
```

### Open the project in Cursor

### Initialize the Sloan MCP

Navigate to `Cursor > Settings > Cursor Settings > Tools and Integrations` then toggle on the `Sloan MCP` tool.

### For best results, set the LLM to `claude-4-sonnet`

Gemini 2.5 and o3 are also reasonably good, but claude-4-sonnet has the most consistent results.

### Create an egress API

You can skip this step if you've already completed the [Egress Demo](/sloan/demos/egress).

<Tabs.Tab>

> Can you create an API that returns every aircraft within X miles of Y,Z coordinates.

</Tabs.Tab>
<Tabs.Tab>

If you prefer to implement the egress API manually, you can create the following analytics API:

```typescript filename="app/index.ts"
...
export * from './apis/getAircraftWithinRadius';

```

```typescript filename="app/apis/getAircraftWithinRadius.ts"

/**
 * Parameters for the getAircraftWithinRadius API
 */
interface AircraftRadiusParams {
  /** Latitude of the center point */
  center_lat: number;

  /** Longitude of the center point */
  center_lon: number;

  /** Radius in miles from the center point */
  radius_miles: number;

  /** Maximum number of results to return (optional) */
  limit?: number & tags.Type<"int64"> & tags.Minimum<1> & tags.Maximum<1000>;
}

/**
 * API to retrieve aircraft within a specified radius from given coordinates
 * Uses ClickHouse's geoDistance function to calculate great circle distance
 */
) => {
    // Execute the query with proper parameter handling
    const result = await client.query.execute(sql`
      SELECT 
        hex,
        flight,
        aircraft_type,
        lat,
        lon,
        alt_baro,
        gs,
        track,
        timestamp,
        round(geoDistance(lon, lat, ${params.center_lon}, ${params.center_lat}) * 0.000621371, 2) as distance_miles
      FROM AircraftTrackingProcessed 
      WHERE geoDistance(lon, lat, ${params.center_lon}, ${params.center_lat}) * 0.000621371 <= ${params.radius_miles}
      ORDER BY distance_miles ASC
      LIMIT ${params.limit || 100}
    `);

    return result;
  },
  {
    metadata: {
      description: "Returns all aircraft within a specified distance (in miles) from given coordinates"
    }
  }
);
```

</Tabs.Tab>

### Prompt the LLM to create a materialized view

> Given the egress API, can you create a materialized view that improves the performance of the query?

### Action

The LLM should now use sloan tools to:
1. analyze the Moose project and the egress API
2. create a Materialized View that pre-aggregates the data

You'll know it is succeeding if:
1. the LLM successfully creates the materialized view
2. the LLM sees that the materialized view was created in the ClickHouse database

### Optional further prompts

> Can you create a new egress API that leverages the materialized view to improve the performance of the query?

> Can you test both APIs to see what the performance difference is?
> I want to see the difference in speed, number of rows read, amount of data read, compute, and other vectors you think are pertinent.