package tools
import (
	"encoding/csv"
	"fmt"
	"io"
	"os"
	"sort"
	"strconv"
)
// Constants for clustering algorithm
const (
	CLUSTER_GAP_MULTIPLIER      = 3 // Gap threshold = CLUSTER_GAP_MULTIPLIER * clip_duration
	MIN_DETECTIONS_PER_CLUSTER  = 1 // Minimum detections per cluster (1 = filter single detections)
)
// ClusteredCall represents a clustered bird call detection
type ClusteredCall struct {
	File       string  `json:"file"`
	StartTime  float64 `json:"start_time"`
	EndTime    float64 `json:"end_time"`
	EbirdCode  string  `json:"ebird_code"`
	Detections int     `json:"detections"`
}
// CallsFromPredsInput defines the input for the calls-from-preds tool
type CallsFromPredsInput struct {
	CSVPath string `json:"csv_path" jsonschema:"required,Path to predictions CSV file"`
}
// CallsFromPredsOutput defines the output for the calls-from-preds tool
type CallsFromPredsOutput struct {
	Calls         []ClusteredCall `json:"calls"`
	TotalCalls    int             `json:"total_calls"`
	TotalClusters int             `json:"total_clusters"`
	ClipDuration  float64         `json:"clip_duration"`
	GapThreshold  float64         `json:"gap_threshold"`
	SpeciesCount  map[string]int  `json:"species_count"`
	FilesCount    int             `json:"files_count"`
	Error         *string         `json:"error,omitempty"`
}
// CallsFromPreds reads a predictions CSV and clusters detections into continuous bird calls
func CallsFromPreds(input CallsFromPredsInput) (CallsFromPredsOutput, error) {
	var output CallsFromPredsOutput
	// Open CSV file
	file, err := os.Open(input.CSVPath)
	if err != nil {
		errMsg := fmt.Sprintf("Failed to open CSV file: %v", err)
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)
	}
	defer file.Close()
	// Read CSV
	reader := csv.NewReader(file)
	reader.ReuseRecord = true // Memory optimization for large files
	// Read header
	header, err := reader.Read()
	if err != nil {
		errMsg := fmt.Sprintf("Failed to read CSV header: %v", err)
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)
	}
	// Find column indices
	fileIdx := -1
	startTimeIdx := -1
	endTimeIdx := -1
	var ebirdCodes []string
	var ebirdIdx []int
	for i, col := range header {
		switch col {
		case "file":
			fileIdx = i
		case "start_time":
			startTimeIdx = i
		case "end_time":
			endTimeIdx = i
		default:
			// All other columns are ebird codes
			ebirdCodes = append(ebirdCodes, col)
			ebirdIdx = append(ebirdIdx, i)
		}
	}
	if fileIdx == -1 || startTimeIdx == -1 || endTimeIdx == -1 {
		errMsg := "CSV must have 'file', 'start_time', and 'end_time' columns"
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)
	}
	if len(ebirdCodes) == 0 {
		errMsg := "CSV must have at least one ebird code column"
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)
	}
	// Read all rows and organize by (file, ebird_code) -> start_times
	// Using maps for efficient grouping
	type FileEbirdKey struct {
		File      string
		EbirdCode string
	}
	detections := make(map[FileEbirdKey][]float64)
	clipDuration := 0.0
	filesSeen := make(map[string]bool)
	// Read first row to get clip duration
	record, err := reader.Read()
	if err != nil && err != io.EOF {
		errMsg := fmt.Sprintf("Failed to read first CSV row: %v", err)
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)
	}
	if err != io.EOF {
		startTime, _ := strconv.ParseFloat(record[startTimeIdx], 64)
		endTime, _ := strconv.ParseFloat(record[endTimeIdx], 64)
		clipDuration = endTime - startTime
		output.ClipDuration = clipDuration
		// Process first row
		fileName := record[fileIdx]
		filesSeen[fileName] = true
		for i, idx := range ebirdIdx {
			if record[idx] == "1" {
				key := FileEbirdKey{File: fileName, EbirdCode: ebirdCodes[i]}
				detections[key] = append(detections[key], startTime)
			}
		}
		// Read remaining rows
		for {
			record, err := reader.Read()
			if err == io.EOF {
				break
			}
			if err != nil {
				errMsg := fmt.Sprintf("Failed to read CSV row: %v", err)
				output.Error = &errMsg
				return output, fmt.Errorf("%s", errMsg)
			}
			startTime, _ := strconv.ParseFloat(record[startTimeIdx], 64)
			fileName := record[fileIdx]
			filesSeen[fileName] = true
			for i, idx := range ebirdIdx {
				if record[idx] == "1" {
					key := FileEbirdKey{File: fileName, EbirdCode: ebirdCodes[i]}
					detections[key] = append(detections[key], startTime)
				}
			}
		}
	}
	// Calculate gap threshold
	gapThreshold := float64(CLUSTER_GAP_MULTIPLIER) * clipDuration
	output.GapThreshold = gapThreshold
	output.FilesCount = len(filesSeen)
	// Cluster detections by (file, ebird_code)
	var allCalls []ClusteredCall
	speciesCount := make(map[string]int)
	for key, startTimes := range detections {
		// Sort start times
		sort.Float64s(startTimes)
		// Cluster consecutive detections
		clusters := clusterStartTimes(startTimes, gapThreshold)
		// Convert clusters to calls
		for _, cluster := range clusters {
			if len(cluster) <= MIN_DETECTIONS_PER_CLUSTER {
				continue
			}
			call := ClusteredCall{
				File:       key.File,
				StartTime:  cluster[0],
				EndTime:    cluster[len(cluster)-1] + clipDuration,
				EbirdCode:  key.EbirdCode,
				Detections: len(cluster),
			}
			allCalls = append(allCalls, call)
			speciesCount[key.EbirdCode]++
		}
	}
	// Sort calls by file, then start time
	sort.Slice(allCalls, func(i, j int) bool {
		if allCalls[i].File != allCalls[j].File {
			return allCalls[i].File < allCalls[j].File
		}
		return allCalls[i].StartTime < allCalls[j].StartTime
	})
	output.Calls = allCalls
	output.TotalCalls = len(allCalls)
	output.TotalClusters = len(allCalls)
	output.SpeciesCount = speciesCount
	return output, nil
}
// clusterStartTimes groups consecutive start times into clusters
// where the gap between consecutive times is <= gapThreshold
func clusterStartTimes(startTimes []float64, gapThreshold float64) [][]float64 {
	if len(startTimes) == 0 {
		return nil
	}
	var clusters [][]float64
	currentCluster := []float64{startTimes[0]}
	for i := 1; i < len(startTimes); i++ {
		gap := startTimes[i] - startTimes[i-1]
		if gap <= gapThreshold {
			// Same cluster
			currentCluster = append(currentCluster, startTimes[i])
		} else {
			// New cluster
			clusters = append(clusters, currentCluster)
			currentCluster = []float64{startTimes[i]}
		}
	}
	// Don't forget the last cluster
	clusters = append(clusters, currentCluster)
	return clusters
}

	case "calls-from-preds":
		cmd.RunCallsFromPreds(os.Args[2:])

	fmt.Fprintf(os.Stderr, "  calls-from-preds  Extract clustered calls from ML predictions CSV\n")

	fmt.Fprintf(os.Stderr, "  %s calls-from-preds --csv predictions.csv > calls.json\n", os.Args[0])

// RunCluster handles the "cluster" subcommand
func RunCluster(args []string) {

// RunRecordingCluster handles the "cluster" subcommand (for database cluster records)
func RunRecordingCluster(args []string) {

		printClusterUsage()

		printRecordingClusterUsage()

		printClusterUsage()

		printRecordingClusterUsage()

func printClusterUsage() {

func printRecordingClusterUsage() {

	fmt.Fprintf(os.Stderr, "  skraak cluster update --db ./db/skraak.duckdb --id cluster123 --name \"Updated Name\"\n")

	fmt.Fprintf(os.Stderr, "  skraak cluster update --db ./db/skraak.duckdb --id clust123 --name \"New Name\"\n")

	sampleRate := fs.Int("sample-rate", 0, "Sample rate in Hz (required, e.g. 250000)")
	path := fs.String("path", "", "Folder path (optional)")
	patternID := fs.String("pattern", "", "Cyclic recording pattern ID (optional)")

	sampleRate := fs.String("sample-rate", "", "Sample rate in Hz (required)")

		fmt.Fprintf(os.Stderr, "Create a new cluster within a location.\n\n")

		fmt.Fprintf(os.Stderr, "Create a new cluster for grouping recordings.\n\n")

	if *sampleRate == 0 {

	if *sampleRate == "" {

		os.Exit(1)
	}
	// Parse sample rate
	sr, err := strconv.Atoi(*sampleRate)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: invalid sample rate: %v\n", err)

	// Build input with optional fields as nil when empty

		DatasetID:  datasetID,
		LocationID: locationID,
		Name:       name,
		SampleRate: sampleRate,
	}
	// Only set optional fields if they have values
	if *path != "" {
		input.Path = path
	}
	if *patternID != "" {
		input.CyclicRecordingPatternID = patternID
	}
	if *description != "" {
		input.Description = description

		DatasetID:   datasetID,
		LocationID:  locationID,
		Name:        name,
		SampleRate:  &sr,
		Description: description,

	sampleRateStr := fs.String("sample-rate", "", "New sample rate in Hz (optional)")
	path := fs.String("path", "", "New folder path (optional)")
	patternID := fs.String("pattern", "", "New cyclic recording pattern ID (optional, use empty to clear)")

	sampleRate := fs.String("sample-rate", "", "New sample rate in Hz (optional)")

		fmt.Fprintf(os.Stderr, "  skraak cluster update --db ./db/skraak.duckdb --id cluster123 --name \"New Name\"\n")

		fmt.Fprintf(os.Stderr, "  skraak cluster update --db ./db/skraak.duckdb --id clust123 --name \"New Name\"\n")

	var sampleRate *int
	if *sampleRateStr != "" {
		sr, err := strconv.Atoi(*sampleRateStr)

	var sr *int
	if *sampleRate != "" {
		srVal, err := strconv.Atoi(*sampleRate)

			fmt.Fprintf(os.Stderr, "Error: invalid sample-rate: %v\n", err)

			fmt.Fprintf(os.Stderr, "Error: invalid sample rate: %v\n", err)

		sampleRate = &sr

		sr = &srVal

	// Build input - only set fields that were provided

	// Build input - only set fields that were provided (non-empty)

	if sampleRate != nil {
		input.SampleRate = sampleRate

	if sr != nil {
		input.SampleRate = sr

	if *path != "" {
		input.Path = path
	}
	if *patternID != "" {
		input.CyclicRecordingPatternID = patternID
	}

package cmd
import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"skraak/tools"
)
// RunCallsFromPreds handles the "calls-from-preds" command
func RunCallsFromPreds(args []string) {
	fs := flag.NewFlagSet("calls-from-preds", flag.ExitOnError)
	csvPath := fs.String("csv", "", "Path to predictions CSV file (required)")
	fs.Usage = func() {
		fmt.Fprintf(os.Stderr, "Usage: skraak calls-from-preds [options]\n\n")
		fmt.Fprintf(os.Stderr, "Extract clustered bird calls from ML predictions CSV.\n")
		fmt.Fprintf(os.Stderr, "Reads prediction CSV with columns: file, start_time, end_time, <ebird_codes...>\n")
		fmt.Fprintf(os.Stderr, "Each row is a clip with 1=present, 0=absent for each species.\n\n")
		fmt.Fprintf(os.Stderr, "Options:\n")
		fs.PrintDefaults()
		fmt.Fprintf(os.Stderr, "\nOutput:\n")
		fmt.Fprintf(os.Stderr, "  JSON with clustered calls (file, start_time, end_time, ebird_code, detections)\n")
		fmt.Fprintf(os.Stderr, "\nExamples:\n")
		fmt.Fprintf(os.Stderr, "  skraak calls-from-preds --csv predictions.csv > calls.json\n")
		fmt.Fprintf(os.Stderr, "  skraak calls-from-preds --csv preds.csv | jq '.calls[] | select(.ebird_code==\"kea1\")'\n")
	}
	if err := fs.Parse(args); err != nil {
		os.Exit(1)
	}
	// Validate required flags
	if *csvPath == "" {
		fmt.Fprintf(os.Stderr, "Error: --csv is required\n\n")
		fs.Usage()
		os.Exit(1)
	}
	input := tools.CallsFromPredsInput{
		CSVPath: *csvPath,
	}
	fmt.Fprintf(os.Stderr, "Extracting calls from predictions: %s\n", *csvPath)
	output, err := tools.CallsFromPreds(input)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
	fmt.Fprintf(os.Stderr, "Found %d clustered calls across %d species in %d files\n",
		output.TotalCalls, len(output.SpeciesCount), output.FilesCount)
	fmt.Fprintf(os.Stderr, "Clip duration: %.1fs, Gap threshold: %.1fs\n",
		output.ClipDuration, output.GapThreshold)
	// Output JSON to stdout
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "  ")
	enc.Encode(output)
}

## [2026-02-22] New CLI Command: calls-from-preds
**New feature:** Extract clustered bird calls from ML predictions CSV files.
**Usage:**
```bash
./skraak calls-from-preds --csv predictions.csv > calls.json
```
**How it works:**
1. Reads prediction CSV (file, start_time, end_time, ebird_code columns with 1/0 values)
2. Auto-detects clip duration from first row
3. Groups detections by (file, ebird_code) and sorts by start_time
4. Clusters consecutive detections where gap ≤ 3 × clip_duration
5. Filters out single detections (configurable via constant)
**Constants (easily changeable):**
```go
CLUSTER_GAP_MULTIPLIER     = 3  // Gap threshold = 3 × clip_duration
MIN_DETECTIONS_PER_CLUSTER = 1  // Filter single detections
```
**Performance:** 400k+ rows processed in ~0.67 seconds

**Output example:**
```json
{
  "calls": [
    {"file": "path.WAV", "start_time": 0, "end_time": 32, "ebird_code": "tomtit1", "detections": 11}
  ],
  "total_calls": 62593,
  "species_count": {"tomtit1": 12636, ...},
  "files_count": 14017
}
```
**Files:**
- `tools/calls_from_preds.go` — Core clustering logic
- `cmd/calls_from_preds.go` — CLI handler
---

me.txt
example/