---
name: import-segments
description: Import classified segments from a single folder of .data files into the database - looks up IDs, creates mapping, runs import
---

# Import Segments from a Single Folder

Import manually classified AviaNZ `.data` file segments into the database for one folder (one cluster).

## When to Use

When the user wants to import classified `.data` files from a folder. The folder must already have `.data` files (from `calls classify` or `calls from-preds`) and the WAV files must already be imported into the database.

## Prerequisites

Before this skill runs, the user should have already:
1. Generated predictions and created `.data` files (`calls from-preds` or similar)
2. Classified calls (`calls classify`)
3. Imported the WAV files into the database (`import folder` or `import bulk`)

## Workflow

### Step 1: Identify the folder

Get the folder path from the user. Confirm `.data` files exist:

```bash
ls <folder>/*.data | head -5
```

### Step 2: Determine dataset, location, and cluster IDs

Extract the cluster/location name from the folder path (e.g., `tx51` from `.../tx51/`). Query the database to find matching IDs:

```bash
./skraak sql --db ./db/skraak.duckdb "SELECT c.id AS cluster_id, c.name AS cluster_name, l.id AS location_id, l.name AS location_name, d.id AS dataset_id, d.name AS dataset_name FROM cluster c JOIN location l ON c.location_id = l.id JOIN dataset d ON l.dataset_id = d.id WHERE c.active = true AND c.name ILIKE '%tx51%'"
```

Adjust the `ILIKE` pattern based on the folder name. If multiple results, ask the user to pick. Show the user the matched dataset/location/cluster and confirm before proceeding.

### Step 3: Check mapping file

Look for an existing `mapping_*.json` in the folder:

```bash
ls <folder>/mapping_*.json
```

If no mapping exists, tell the user to run the `skraak-data-mapping` skill first:

```
No mapping file found. Please run: /skraak-data-mapping
```

Then stop and wait for the user.

### Step 4: Run the import

```bash
./skraak import segments \
  --db ./db/skraak.duckdb \
  --dataset <dataset_id> \
  --location <location_id> \
  --cluster <cluster_id> \
  --folder "<folder_path>" \
  --mapping "<folder_path>/mapping_YYYY-MM-DD.json"
```

Use the production database (`./db/skraak.duckdb`) unless the user specifies otherwise.

### Step 5: Report results

Show the user the import summary from the JSON output:
- Data files processed
- Segments imported
- Labels imported
- Any errors

## Error Handling

- If no `.data` files found: abort with clear message
- If cluster/location not found in DB: ask user for the correct name or IDs
- If files not yet imported (hash mismatch): tell user to run `import folder` first
- If segments already have labels: warn user - `import segments` only works on files with no existing labels