---

Uwatu Intelligence Layer

Overview

The Uwatu Intelligence Layer is a high-performance, hybrid decision engine designed for real-time livestock monitoring. It processes incoming telemetry and network signals from physical collars via a Go backend, evaluates the data across four distinct analytical layers, and returns a standardized, actionable event payload.

This microservice is built with FastAPI and utilizes a multi-tiered architecture that prioritizes deterministic rules for immediate threats, falls back to statistical and machine learning models for subtle anomalies, and leverages Generative AI to translate complex data into human-readable SMS advisories.

System Architecture

The decision engine operates on a strict hierarchy to optimize for speed, accuracy, and computational efficiency.

• Layer 1: Deterministic Reflexes

• Evaluates immediate, high-confidence threats that do not require historical context.

• Triggers: Cellular SIM Swaps (theft), Geofence Breaches (theft), and Nighttime Stampedes (predator attacks).

• Layer 2: Statistical Baseline Engine

• An O(1) memory engine utilizing Welford's online algorithm.

• Normalizes animal movement using a 48-slot time-of-day array.

• Computes real-time Z-scores to differentiate standard cyclical behavior (e.g., morning grazing) from abnormal pacing or lethargy.

• Layer 3: Machine Learning Inference

• A feature extraction pipeline that flattens nested JSON telemetry into a strict 15-item NumPy array.

• Evaluates the feature vector against an Isolation Forest model to detect multivariate health anomalies that bypass static rules.

• Layer 4: Generative AI Narrator

• Utilizes the gemini-2.5-flash-lite model via the Google Generative AI SDK.

• Translates raw JSON anomaly data into calm, localized, actionable SMS alerts strictly under 160 characters.

• Includes hardcoded text fallbacks to ensure system resilience during API outages.

Project Structure

uwatu-intelligence/
├── app/
│   ├── main.py                     # FastAPI application router and entry point
│   ├── models/
│   │   ├── signal_matrix.py        # Input Pydantic contract (Telemetry, Context, Nokia API)
│   │   ├── scored_event.py         # Output Pydantic contract 
│   │   └── baseline.py             # Welford variance math and time-of-day normalizer
│   ├── classifier/
│   │   ├── event_classifier.py     # Master decision routing logic
│   │   ├── theft_rules.py          # Layer 1: SIM Swap and Geofence rules
│   │   └── predator_rules.py       # Layer 1: Stampede detection
│   ├── scoring/
│   │   └── feature_builder.py      # Layer 3: Array extraction and ML simulation
│   └── gemini/
│       └── narrator.py             # Layer 4: GenAI prompt builder and fallback logic
├── requirements.txt
└── README.md

Installation and Setup

1. Clone the repository and navigate to the directory.
2. Set up a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure Environment Variables: You must expose your Google Gemini API key to the environment for Layer 4 to function.

export GEMINI_API_KEY="your_api_key_here"

Running the Application

Start the FastAPI server using Uvicorn.

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

The service will be available at http://localhost:8000. You can view the automatic Swagger documentation and test the API contracts directly at http://localhost:8000/docs.

API Contracts

Input: The Signal Matrix

The endpoint /score expects a POST request containing the SignalMatrix JSON payload. This includes nested objects for:

• telemetry: Hardware sensor data (accelerometer, temperature, battery).
• nokia_signals: Telecommunications data (SIM status, cell congestion, network slicing).
• baseline: Historical aggregates.
• context: Environmental state (time of day, market schedules).

Output: The Scored Event

The service guarantees a return of the ScoredEvent object, containing:

• request_id: Mapped directly from the input for tracing.
• event_type: The classification (e.g., NORMAL_VARIATION, THEFT_HIGH_CONFIDENCE).
• confidence: A float representing analytical certainty.
• gemini_narrative: The formatted SMS text (if an anomaly was detected).

Versioning

Current Model Version: 1.0.0-hybrid This tag tracks the specific combination of deterministic rules and ML logic used to score an event, ensuring accurate data lineage as the models evolve over time.