SIRUP: Spatio-temporal Intelligence for Reasoning and Unified Perception

Imported from agstack/pancake · docs/SIRUP.md
Edits belong in that repository, not in agstack/docs. Licensed under EUPL-1.2, not this site's CC BY-SA 4.0.

Version: 1.0
Status: Proof of Concept
Purpose: Enriched data payload standard for agricultural intelligence

Overview
The Raw Data Problem
What is SIRUP?
The Maple Syrup Metaphor
SIRUP Components
Design Philosophy
SIRUP vs Raw Data
Design Rationale
SIRUP Types
Quality Indicators
Future: SIRUP Certification

Overview

SIRUP (Spatio-temporal Intelligence for Reasoning and Unified Perception) is enriched agricultural data that flows through TAP pipelines. It’s not just raw numbers—it’s intelligence-ready data with spatial context, temporal markers, and semantic metadata.

The Core Concept

Raw data: {"value": 0.65}
SIRUP:

{
  "value": 0.65,
  "what": "NDVI",
  "where": "field-abc (24.5°N, 54.4°E)",
  "when": "2024-10-31T12:00:00Z",
  "who": "Sentinel-2 satellite",
  "how": "10m resolution, cloud-free",
  "why": "vegetation health monitoring",
  "quality": "high (cloud_cover: 0%, confidence: 95%)"
}

SIRUP = Raw Data + Context + Quality + Semantics

The Raw Data Problem

Scenario: Satellite Imagery from Three Vendors

Vendor A (Planet.com):

{
  "scene_id": "20241031_123456",
  "ndvi": 0.65,
  "cloud_percent": 5
}

Vendor B (terrapipe.io):

{
  "date": "2024-10-31",
  "ndvi_img": {
    "features": [
      {"properties": {"NDVI": 0.64}},
      {"properties": {"NDVI": 0.66}}
    ]
  },
  "boundary_geoDataFrameDict": {...}
}

Vendor C (Sentinel Hub):

{
  "outputs": {
    "default": {
      "bands": {
        "B04": [...],
        "B08": [...]
      }
    }
  }
}

The Integration Nightmare

Problem 1: Format chaos

Same data type (NDVI), three incompatible formats
Farmer’s app must handle all three (or only supports one)

Problem 2: Missing context

What resolution? (10m? 30m? 1m?)
Which sensor? (Sentinel-2? Landsat? Planet?)
How computed? (Algorithm version?)
Quality? (Cloud cover? Confidence score?)

Problem 3: Not AI-ready

LLMs can’t interpret without extensive parsing
Machine learning models need consistent features
Human analysts confused (“Which vendor is accurate?”)

Result: Raw data is opaque (hard to interpret), inconsistent (varies by vendor), and untrustworthy (no quality signals).

What is SIRUP?

SIRUP is data that has been enriched with:

Spatial context: Where was this measured? (coordinates, boundaries, resolution)
Temporal context: When was this captured? (acquisition time, validity period)
Semantic metadata: What does this mean? (units, sensor, algorithm)
Quality indicators: How trustworthy is this? (confidence, completeness, accuracy)
Provenance: Who created this? (vendor, sensor, processing pipeline)

SIRUP as “Intelligence-Ready” Data

Analogy: Sugar vs Maple Syrup

Sugar (raw data): Crystalline, needs dissolving, one-dimensional
Maple Syrup (SIRUP): Liquid, ready-to-use, rich (minerals, flavor, complexity)

SIRUP data:

No additional processing needed for AI/ML
Context embedded (no external lookups)
Quality transparent (trust immediately)
Semantically rich (LLMs understand)

SIRUP Flow Through TAP

Vendor Raw Data → TAP Adapter → SIRUP Enrichment → BITE (Body = SIRUP) → PANCAKE

Example:

Vendor: terrapipe.io returns raw NDVI GeoJSON
TAP Adapter: Extracts NDVI, computes statistics, adds metadata
SIRUP: Enriched payload with context
BITE Body: Contains SIRUP (standardized)
PANCAKE: Stores BITE, generates embedding, indexes

The Maple Syrup Metaphor

Why “SIRUP”?

Maple syrup is to tree sap as SIRUP data is to raw vendor data:

Tree Sap (Raw Data):

Collected from trees (sensors, satellites)
Watery, diluted (lots of volume, little value)
Not ready to consume (needs processing)

Maple Syrup (SIRUP):

Concentrated (40 gallons sap → 1 gallon syrup)
Rich, complex (minerals, antioxidants, flavor)
Ready to use (pour on pancakes 🥞)

Agricultural Parallel:

Raw Satellite Data (Sap):

10GB GeoTIFF file
Requires GIS expertise to interpret
Missing quality indicators

SIRUP Satellite Data (Syrup):

10KB JSON with NDVI statistics
Self-describing (units, resolution, confidence)
Ready for AI/ML pipelines

The Concentration Process

Maple Syrup: Boil sap, evaporate water, concentrate sugars

SIRUP: TAP Adapter processes raw data

Extract: Pull relevant values (NDVI from GeoTIFF)
Compute: Calculate statistics (mean, min, max, std)
Contextualize: Add metadata (sensor, resolution, timestamp)
Validate: Check quality (cloud cover, completeness)
Enrich: Include provenance, units, semantics

Result: From 10GB → 10KB, 1000x concentration, 100% usable.

Why This Matters

Farmers don’t want tree sap; they want syrup.
Apps don’t want raw data; they want SIRUP.

SIRUP is consumption-ready intelligence.

SIRUP Components

1. Spatio-temporal Context

Spatial: Where is this data?

{
  "spatial_context": {
    "geoid": "63f764609b85eb356d387c1630a0671d3a8a56ffb6c91d1e52b1d7f2fe3c4213",
    "geometry_type": "Polygon",
    "area_hectares": 12.5,
    "centroid": {
      "lat": 24.536,
      "lon": 54.427
    },
    "resolution_meters": 10,
    "coordinate_system": "WGS84"
  }
}

Why this matters:

Scale: 10m resolution vs 1m resolution = different use cases
Area: Small field (1 ha) vs large farm (100 ha) = different analysis
Location: Coordinates enable spatial queries, proximity analysis

Temporal: When is this data from?

{
  "temporal_context": {
    "acquisition_time": "2024-10-31T12:34:56Z",
    "processing_time": "2024-10-31T14:00:00Z",
    "validity_start": "2024-10-31",
    "validity_end": "2024-11-01",
    "timezone": "UTC",
    "season": "spring",
    "growth_stage": "flowering"
  }
}

Why this matters:

Timeliness: Data from yesterday vs last month = different relevance
Seasonality: Spring vs fall = different interpretation
Growth stage: Flowering vs harvest = different patterns

2. Semantic Metadata

What does this data mean?

{
  "semantics": {
    "data_type": "NDVI",
    "full_name": "Normalized Difference Vegetation Index",
    "units": "unitless",
    "range": [-1.0, 1.0],
    "interpretation": {
      "< 0.2": "bare soil, water, or non-vegetated",
      "0.2-0.4": "sparse vegetation",
      "0.4-0.6": "moderate vegetation",
      "0.6-0.8": "dense vegetation",
      "> 0.8": "very dense vegetation (rainforest)"
    },
    "purpose": "vegetation health monitoring"
  }
}

Why this matters:

Interpretation: NDVI 0.65 means “healthy crops” (not just a number)
Context: Farmer knows what values are good/bad
AI-ready: LLM can explain (“Your NDVI of 0.65 indicates healthy vegetation”)

3. Provenance

Who created this data? How?

{
  "provenance": {
    "vendor": "terrapipe.io",
    "sensor": "Sentinel-2 MSI",
    "satellite": "Sentinel-2B",
    "algorithm": "NDVI = (B08 - B04) / (B08 + B04)",
    "algorithm_version": "1.2.3",
    "processing_level": "L2A",
    "pipeline": "TAP-terrapipe-v1.0.2",
    "license": "Creative Commons CC-BY-4.0"
  }
}

Why this matters:

Trust: Know source (vendor reputation)
Reproducibility: Same algorithm = consistent results
Compliance: License tracking (legal use)
Debugging: Algorithm version helps trace errors

4. Quality Indicators

How trustworthy is this data?

{
  "quality": {
    "overall_score": 0.95,
    "confidence": 0.95,
    "completeness": 1.0,
    "accuracy": "±0.05 NDVI units",
    "cloud_cover": 0.02,
    "shadow_cover": 0.00,
    "data_gaps": 0,
    "outliers_removed": 3,
    "calibration_status": "valid",
    "validation_passed": true
  }
}

Why this matters:

Decision-making: High quality (0.95) = trust, low quality (0.50) = verify
Filtering: Exclude low-quality data from analysis
Transparency: Know limitations (±0.05 accuracy)

5. Statistical Summary

What are the key numbers?

{
  "statistics": {
    "mean": 0.65,
    "median": 0.64,
    "min": 0.45,
    "max": 0.85,
    "std": 0.08,
    "count": 1250,
    "percentiles": {
      "p10": 0.55,
      "p25": 0.60,
      "p50": 0.64,
      "p75": 0.70,
      "p90": 0.75
    }
  }
}

Why this matters:

Summary: No need to process raw pixels (pre-computed)
Variability: High std (0.15) = uneven field, low std (0.05) = uniform
Outliers: Min/max reveal anomalies

Design Philosophy

Principle 1: Self-Describing

SIRUP data should be understandable without external documentation.

Bad (Raw Data):

{"ndvi": 0.65}

Questions: What’s NDVI? What sensor? When? Where?

Good (SIRUP):

{
  "ndvi": {
    "value": 0.65,
    "description": "Normalized Difference Vegetation Index",
    "sensor": "Sentinel-2 MSI",
    "date": "2024-10-31"
  }
}

Questions: Answered inline.

Principle 2: AI-Native

SIRUP should be directly consumable by LLMs and ML models.

LLM consumption:

sirup_text = json.dumps(sirup_data)
response = llm.ask(f"Analyze this vegetation data: {sirup_text}")
# LLM can interpret because metadata is rich

ML model consumption:

features = [
    sirup["statistics"]["mean"],
    sirup["statistics"]["std"],
    sirup["spatial_context"]["area_hectares"],
    sirup["temporal_context"]["season_numeric"],
    sirup["quality"]["confidence"]
]
# Model gets both data AND quality/context features

Principle 3: Quality-Aware

SIRUP must include trust indicators.

Use case: Model training

# Only train on high-quality data
high_quality = [s for s in sirups if s["quality"]["overall_score"] > 0.8]

Use case: Alert thresholds

if sirup["statistics"]["mean"] < 0.4 and sirup["quality"]["confidence"] > 0.9:
    alert("Low NDVI detected with high confidence!")

Principle 4: Vendor-Neutral

SIRUP should hide vendor-specific quirks.

Vendor A (raw): {"cloud_pct": 5}
Vendor B (raw): {"cloud_coverage": 0.05}
Vendor C (raw): {"clouds": "5%"}

SIRUP (unified):

{
  "quality": {
    "cloud_cover": 0.05  // Always 0-1 range, always "cloud_cover" field
  }
}

Benefit: Apps don’t care which vendor; SIRUP is consistent.

Principle 5: Efficiency

SIRUP should be compact (not raw pixels).

Raw satellite image: 10GB GeoTIFF (10000×10000 pixels)
SIRUP summary: 10KB JSON (statistics + metadata)
Compression ratio: 1,000,000:1

When raw needed: Link to original

{
  "raw_data_uri": "s3://terrapipe-data/field-abc/2024-10-31.tif",
  "raw_data_hash": "sha256:abc123..."
}

SIRUP vs Raw Data

Comparison Table

Aspect	Raw Data	SIRUP
Size	10GB (GeoTIFF)	10KB (JSON)
Format	Vendor-specific	Standardized
Context	Missing	Embedded
Quality	Unknown	Explicit
AI-ready	No (needs preprocessing)	Yes (direct use)
Human-readable	No (binary/complex)	Yes (JSON)
Interoperable	No (vendor lock-in)	Yes (BITE-wrapped)

Example: NDVI Comparison

Raw Data (Vendor A)

{
  "scene_id": "20241031_123456_0e1c",
  "product_type": "PSScene4Band",
  "strip_id": "7654321",
  "cloud_cover": 0.05,
  "sun_elevation": 45.6,
  "sun_azimuth": 135.2,
  "view_angle": 2.3,
  "assets": {
    "analytic": {
      "href": "https://vendor-a.com/download/xyz.tif"
    }
  }
}

Problems:

NDVI not computed (need to download GeoTIFF, process)
Field boundary not included
Units unclear
No quality score

SIRUP (from Raw Data)

{
  "sirup_type": "satellite_ndvi",
  "vendor": "vendor-a",
  "date": "2024-10-31",
  
  "spatial_context": {
    "geoid": "field-abc",
    "area_hectares": 12.5,
    "resolution_meters": 3
  },
  
  "temporal_context": {
    "acquisition_time": "2024-10-31T10:45:00Z",
    "season": "spring"
  },
  
  "semantics": {
    "data_type": "NDVI",
    "units": "unitless",
    "range": [-1, 1]
  },
  
  "statistics": {
    "mean": 0.65,
    "min": 0.45,
    "max": 0.85,
    "std": 0.08,
    "count": 15625  // pixels
  },
  
  "quality": {
    "overall_score": 0.95,
    "cloud_cover": 0.05,
    "confidence": 0.95
  },
  
  "provenance": {
    "vendor": "vendor-a",
    "sensor": "PlanetScope PSB.SD",
    "algorithm": "NDVI = (NIR - Red) / (NIR + Red)"
  },
  
  "raw_data": {
    "available": true,
    "uri": "https://vendor-a.com/download/xyz.tif",
    "size_mb": 45.3
  }
}

Benefits:

NDVI pre-computed (no download needed)
Context explicit (where, when, how)
Quality transparent (0.95 score)
Statistics ready (mean, std, etc.)
Provenance clear (sensor, algorithm)

Design Rationale

Decision 1: Summary Statistics vs Full Raster

Options:

Summary only (mean, min, max, std)
Full raster (all pixel values)
Hybrid (summary + link to raster)

Decision: Hybrid (SIRUP = summary, link to raw)

Rationale:

80/20 rule: 80% of use cases need only summary
Efficiency: 10KB summary vs 10GB raster
Flexibility: Link to raw for deep analysis

Use cases:

Dashboard: Display mean NDVI (summary sufficient)
Trend: Plot NDVI over time (summary sufficient)
Zoning: Create prescription map (need full raster, follow link)

Decision 2: Explicit Quality vs Implicit

Options:

Explicit (quality.overall_score: 0.95)
Implicit (user infers from cloud_cover, etc.)

Decision: Explicit

Rationale:

Clarity: No guessing (0.95 = high quality)
Consistency: Vendors compute score uniformly
Filtering: Easy threshold (>0.8 = use, <0.5 = discard)

Alternative rejected (implicit):

Ambiguity: Is 5% cloud cover acceptable? Depends on use case.
Complexity: User must combine multiple factors (cloud + shadow + calibration)

Decision 3: Vendor-Specific Fields

Question: Allow vendor-specific fields in SIRUP?

Decision: Yes, in namespaced section

Example:

{
  "sirup_type": "satellite_ndvi",
  "statistics": {...},  // Standard
  "quality": {...},      // Standard
  
  "vendor_specific": {  // Namespaced
    "terrapipe_calibration_id": "xyz",
    "terrapipe_processing_cluster": "us-east-1"
  }
}

Rationale:

Extensibility: Vendors can innovate (add proprietary metrics)
Interoperability: Standard fields ensure compatibility
Transparency: Namespace makes clear what’s vendor-specific

Decision 4: Units Always Explicit

Question: Assume standard units or specify?

Decision: Always specify

Bad:

{"nitrogen": 45}  // mg/L? ppm? kg/ha?

Good:

{
  "nitrogen": {
    "value": 45,
    "units": "ppm"
  }
}

Rationale:

Safety: Agriculture is regulated (wrong units = wrong application)
Clarity: No assumptions (international users)
AI-ready: LLMs can reason about units

Decision 5: Temporal Validity Period

Question: Single timestamp or range?

Decision: Range (validity_start, validity_end)

Example:

{
  "temporal_context": {
    "acquisition_time": "2024-10-31T12:00:00Z",
    "validity_start": "2024-10-31",
    "validity_end": "2024-11-07"
  }
}

Rationale:

Satellite data: Valid for ~1 week (until next image)
Sensor data: Valid until next reading
Query optimization: Filter by validity range

SIRUP Types

1. Satellite Imagery SIRUP

Type: imagery_sirup

Components:

NDVI, EVI, RGB, thermal
Spatial: resolution, coverage, projection
Temporal: acquisition time, revisit frequency
Quality: cloud cover, shadow, calibration

Example (NDVI):

{
  "sirup_type": "satellite_ndvi",
  "statistics": {
    "mean": 0.65,
    "std": 0.08
  },
  "spatial_context": {
    "resolution_meters": 10,
    "sensor": "Sentinel-2"
  },
  "quality": {
    "cloud_cover": 0.05,
    "confidence": 0.95
  }
}

2. Weather SIRUP

Type: weather_sirup

Components:

Temperature, precipitation, humidity, wind
Spatial: location, interpolation method
Temporal: timestamp, forecast_horizon
Quality: station_distance, confidence

Example:

{
  "sirup_type": "weather_daily",
  "statistics": {
    "temp_max_c": 28.5,
    "temp_min_c": 18.2,
    "precipitation_mm": 12.5
  },
  "spatial_context": {
    "geoid": "field-abc",
    "nearest_station_km": 5.2
  },
  "quality": {
    "confidence": 0.90,
    "data_source": "DTN AgroNom"
  }
}

3. Sensor SIRUP

Type: sensor_sirup

Components:

Soil moisture, temperature, EC, pH
Spatial: depth, location within field
Temporal: reading frequency
Quality: battery level, calibration status

Example:

{
  "sirup_type": "soil_moisture_sensor",
  "statistics": {
    "mean": 23.5,
    "readings_count": 144  // Every 10 minutes for 24h
  },
  "spatial_context": {
    "depth_cm": 15,
    "sensor_id": "cropx-abc-001"
  },
  "quality": {
    "battery_percent": 85,
    "calibration_valid": true,
    "confidence": 0.95
  }
}

4. Lab Analysis SIRUP

Type: lab_sirup

Components:

Soil nutrients (N, P, K), pH, organic matter
Spatial: sample location, depth
Temporal: sample date, lab processing date
Quality: lab certification, method accuracy

Example:

{
  "sirup_type": "soil_lab_analysis",
  "measurements": {
    "nitrogen_ppm": 45.3,
    "phosphorus_ppm": 12.1,
    "ph": 6.8
  },
  "spatial_context": {
    "geoid": "field-abc",
    "sample_depth_cm": 30
  },
  "quality": {
    "lab_certified": true,
    "method": "Mehlich-3",
    "confidence": 0.99
  }
}

5. Pest/Disease SIRUP

Type: pest_disease_sirup

Components:

Trap counts, disease incidence
Spatial: trap locations, affected area
Temporal: monitoring period
Quality: trap quality, identification confidence

Example:

{
  "sirup_type": "pest_trap_monitoring",
  "statistics": {
    "total_insects": 127,
    "target_pest_count": 23,
    "pressure_level": "moderate"
  },
  "spatial_context": {
    "trap_count": 10,
    "area_hectares": 12.5
  },
  "quality": {
    "trap_condition": "good",
    "identification_confidence": 0.92
  }
}

Quality Indicators

Quality Score Computation

Formula (example):

quality_score = 
    0.3 * completeness +        // All expected data present?
    0.3 * accuracy +             // Measurement precision
    0.2 * confidence +           // Algorithm/model confidence
    0.2 * timeliness             // Data freshness

Ranges:

0.9-1.0: Excellent (use with confidence)
0.7-0.9: Good (use with awareness of limitations)
0.5-0.7: Fair (verify with other sources)
<0.5: Poor (discard or flag for review)

Confidence vs Accuracy

Confidence: How sure are we of the measurement?

Affected by: cloud cover, sensor calibration, algorithm complexity
Example: NDVI with 0% clouds = high confidence (0.95)

Accuracy: How close to true value?

Affected by: sensor precision, calibration, processing method
Example: ±0.05 NDVI units = high accuracy

Both matter:

High confidence, low accuracy: “We’re sure, but it might be wrong” (poorly calibrated sensor)
Low confidence, high accuracy: “It’s probably right, but we’re not sure” (cloudy day, good sensor)

Quality Flags

Common flags:

{
  "quality": {
    "overall_score": 0.85,
    "flags": [
      "high_cloud_cover",       // >20% clouds
      "partial_coverage",       // Missing data in corners
      "low_sun_angle",          // Sun <30° (long shadows)
      "interpolated"            // Gap-filled data
    ],
    "warnings": [
      "Use with caution for precision applications"
    ]
  }
}

Automated filtering:

# Only use SIRUP with no critical flags
def is_usable(sirup):
    critical_flags = ["sensor_malfunction", "invalid_calibration"]
    return not any(f in sirup["quality"]["flags"] for f in critical_flags)

Future: SIRUP Certification

Vision: Trusted SIRUP Seal

Problem: How do farmers know SIRUP data is high-quality?

Solution: SIRUP Certification (like organic certification for food)

Certification Levels:

Level 1: SIRUP-Basic

Includes spatial, temporal, semantic, provenance
Quality indicators present
Vendor self-attested

Level 2: SIRUP-Verified

Independent validation (third-party lab tests)
Cross-vendor comparisons (consistency checks)
Transparent methodology

Level 3: SIRUP-Certified

Audited by standards body
Regular re-certification (annually)
Insurance/warranty (vendor liability)

Certification Mark

Example:

{
  "sirup_type": "satellite_ndvi",
  "certification": {
    "level": "SIRUP-Verified",
    "certifying_body": "AgStack Standards Committee",
    "issue_date": "2024-01-15",
    "expiry_date": "2025-01-15",
    "certificate_id": "SIRUP-CERT-2024-001",
    "validation_tests_passed": 47,
    "validation_tests_total": 50
  }
}

Benefits:

Trust: Farmers know quality is independently verified
Accountability: Vendors incentivized to maintain standards
Market differentiation: Certified SIRUP commands premium

Conclusion

SIRUP transforms raw agricultural data into intelligence-ready payloads:

Self-describing: No external docs needed
AI-native: LLMs and ML models consume directly
Quality-aware: Trust indicators embedded
Vendor-neutral: Consistent regardless of source
Efficient: Compact summaries, links to raw

Why SIRUP matters:

Today: Raw data is opaque, inconsistent, hard to use
Future: SIRUP data is transparent, standardized, ready for AI

SIRUP is the “sweet spot” between raw data and processed insights—concentrated intelligence, ready to pour. 🍁

Next steps:

Vendors: Enrich your data as SIRUP (TAP adapters help)
Developers: Consume SIRUP from BITEs (no preprocessing needed)
Farmers: Demand SIRUP-certified data (quality guarantee)

The future of agricultural data is rich, contextual, and trustworthy—just like SIRUP. 🥞

Document Status: Conceptual design (v1.0 POC)
Last Updated: November 2024
Feedback: https://github.com/agstack/sirup/issues
License: CC BY 4.0 (Creative Commons Attribution)

SIRUP: Spatio-temporal Intelligence for Reasoning and Unified Perception

Table of Contents

Overview

The Core Concept

The Raw Data Problem

Scenario: Satellite Imagery from Three Vendors

The Integration Nightmare

What is SIRUP?

SIRUP as “Intelligence-Ready” Data

SIRUP Flow Through TAP

The Maple Syrup Metaphor

Why “SIRUP”?

The Concentration Process

Why This Matters

SIRUP Components

1. Spatio-temporal Context

2. Semantic Metadata

3. Provenance

4. Quality Indicators

5. Statistical Summary

Design Philosophy

Principle 1: Self-Describing

Principle 2: AI-Native

Principle 3: Quality-Aware

Principle 4: Vendor-Neutral

Principle 5: Efficiency

SIRUP vs Raw Data

Comparison Table

Example: NDVI Comparison

Raw Data (Vendor A)

SIRUP (from Raw Data)

Design Rationale

Decision 1: Summary Statistics vs Full Raster

Decision 2: Explicit Quality vs Implicit

Decision 3: Vendor-Specific Fields

Decision 4: Units Always Explicit

Decision 5: Temporal Validity Period

SIRUP Types

1. Satellite Imagery SIRUP

2. Weather SIRUP

3. Sensor SIRUP

4. Lab Analysis SIRUP

5. Pest/Disease SIRUP

Quality Indicators

Quality Score Computation

Confidence vs Accuracy

Quality Flags

Future: SIRUP Certification

Vision: Trusted SIRUP Seal

Certification Mark

Conclusion