@terra-oracle/terra-oracle

A stateless NPM package for hyper-local climate analysis for Plants and Animals using real-time satellite weather data, historical archives, and 7-day thermal forecasts.

Part of the Agri-Oracle: Decentralized Climate Adaptation Protocol.

What It Does

1. Dual-Category Analysis: Specialized thermal analysis for both Plants (Crops) and Animals (Livestock/Poultry).
2. Auto-Location: Resolves position using a GPS-first hybrid strategy (Browser GPS → Reverse Geocoding → IP Fallback).
3. Heatwave Forecasting: Provides 7-day thermal forecasts (Max/Min Temps + Humidity) to predict heatwaves.
4. Historical Comparison: Fetches seasonal averages (Q1-Q4) and comparison data from previous years.
5. AI-Ready: Generates a structured Fact Sheet JSON optimized for interpretation by Generative AI (like Google Gemini).

⚠️ Security First: This package does NOT accept or use an AI API key. The key must live securely in your frontend application.

Installation

npm install @terra-oracle/terra-oracle

Basic Usage

The package automatically detects whether you are analyzing a plant or an animal.

1. Plant Analysis (Default)

import { analyzeField } from '@terra-oracle/terra-oracle';

const factSheet = await analyzeField({
  subject: 'Oil Palm',
  category: 'PLANT' 
});

2. Animal Analysis (Heatwave Focus)

For animals, the SDK automatically includes humidity and a 7-day forecast to help detect heat stress.

const factSheet = await analyzeField({
  subject: 'Broiler Chicken',
  category: 'ANIMAL' 
});

Extended Data Configuration

You can configure the depth of analysis using the config object:

const factSheet = await analyzeField({
  subject: 'Cassava',
  config: {
    includeForecast: true,   // 7-day thermal trend
    includeSeasonal: true,   // Q1-Q4 averages for the previous year
    includeHistory: true,    // Comparison with the same month in past 3 years
    includeProjections: true // Future climate estimates (1-5 years)
  }
});

Precision Mode (Manual Coordinates)

If your app already has GPS coordinates (e.g. from a mobile GPS or map pin), you can skip auto-detection:

const factSheet = await analyzeField({
  subject: 'Maize',
  manualCoords: { lat: 6.5244, lon: 3.3792 }
});

Integration with Gemini AI

Use the "Fact Sheet" to get expert climate advice:

import { analyzeField } from '@terra-oracle/terra-oracle';
import { GoogleGenerativeAI } from '@google/generative-ai';

async function getClimateAdvice(subject: string, type: 'PLANT' | 'ANIMAL') {
  // 1. Get the Data Layer Fact Sheet
  const factSheet = await analyzeField({ 
    subject, 
    category: type 
  });

  // 2. Initialize Gemini
  const genAI = new GoogleGenerativeAI('YOUR_API_KEY');
  const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

  const prompt = `
    You are an expert ${type === 'PLANT' ? 'agronomist' : 'veterinarian'}. 
    FIELD CONDITIONS: ${JSON.stringify(factSheet)}
    Provide immediate actions to mitigate thermal stress for ${subject}.
  `;

  const result = await model.generateContent(prompt);
  return result.response.text();
}

Output Format (Animal Example)

{
  "subject_name": "Poultry",
  "subject_category": "ANIMAL",
  "environmental_snapshot": {
    "location": "Cotonou, Benin",
    "city": "Cotonou",
    "country": "Benin",
    "latitude": 6.3654,
    "longitude": 2.4183,
    "temp_c": 32.5,
    "humidity": 78,
    "source": "Open-Meteo Satellite",
    "timestamp": "2026-04-18T12:00:00Z",
    "forecast": {
      "days": ["2026-04-18", ...],
      "max_temps": [34.2, 35.5, ...],
      "min_temps": [24.1, 25.0, ...],
      "avg_humidity": [75, 80, ...]
    }
  },
  "alerts": [
    {
      "type": "HEAT_WAVE_MODERATE",
      "level": "WARNING",
      "message": "ORACLE MODERATE: High heat detected at 32.5°C."
    }
  ]
}

Geolocation Strategy

The package uses a robust three-tier system:

1. Manual: Priority coordinates provided by the caller.
2. GPS + Reverse Geocode: High-precision navigator.geolocation paired with BigDataCloud for accurate city/country names (avoids IP routing errors).
3. IP Geolocation: Reliable fallback via ipapi.co.

License

MIT