# AGRIOS: from observations to accountable action

AGRIOS stands for Agricultural Intelligence Operating System. Its proposed role is to give agricultural devices, models and machines a shared way to describe data, capabilities, decisions and execution results. A sensor connection becomes useful when another service can understand the measurement and an operator can see what happened because of it.

This package is an interactive browser demonstration of that idea. It runs simulated devices, a simplified farm scene, deterministic decision rules and illustrative models. It does not connect to physical equipment, provide a hosted backend or execute a trained AI service. Its interfaces are demonstration contracts, not an already published AGRIOS API or SDK.

## The problem the demonstration addresses

Without a common contract, a soil sensor may expose a vendor-specific number, a dashboard may draw it without knowing whether it is fresh, and an irrigation controller may accept an unrelated command. The missing work is meaning and accountability: which asset, which unit, whether the input is trustworthy, who approved the action, whether the machine accepted it and what the next measurement showed.

The demonstrator makes this chain visible. Adding a component means describing its capability and mapping its data; it does not mean rewriting the complete agricultural workflow.

## Seven visible layers

The layers are an explanatory view of responsibilities. They are not seven mandatory network hops, separate servers or a requirement that every event visit every layer.

| Layer | Inputs | Work | Outputs |
|---|---|---|---|
| 1. Data acquisition | Device identity, native payload, timestamp | Receive a measurement or machine state | Raw event with source and receiving time |
| 2. Data management | Raw event and device manifest | Check schema, unit, range, time and asset association | Normalized observation, or rejection with a reason |
| 3. Smart alerts | Valid observations and event history | Evaluate thresholds, persistence and missing data | Evidence-linked event requiring attention |
| 4. Analytics | Accepted observations and operational history | Calculate trends and scenario indicators | Values with units, interval and calculation context |
| 5. Digital twin | Accepted state and model parameters | Evaluate an illustrative alternative action | Predicted scenario outcome and stated assumptions |
| 6. Advisory | Evidence, rules, alternative outcomes, constraints | Explain a recommended response | Proposed action requiring operator approval |
| 7. Action and robotics | Approved, bounded action and matching capability | Offer the task and monitor execution | Acceptance, progress, completion or failure, then feedback |

“AI Advisory” in the original concept describes a future service category. The demonstration uses explicit rules. A convincing explanation is more useful here than a fabricated model-confidence score.

## Three practical scenarios

| Scenario | What needs attention | Decision to inspect | Evidence that closes the loop |
|---|---|---|---|
| Irrigation | A monitored soil zone becomes dry | Whether the available observations justify a bounded irrigation action | Simulated valve state and subsequent soil response |
| Robot scouting | A crop zone needs inspection | Which registered robot has the required capability and an acceptable operating state | Mission acceptance, visible movement, progress and a simulated inspection result |
| Greenhouse humidity | Indoor humidity is elevated | Whether ventilation is appropriate under the example conditions | Simulated actuator response and updated indoor climate |

Thresholds and model parameters are demonstration assumptions. They are not agronomic recommendations for every crop, soil, greenhouse or weather condition. Scene geometry and robot movement explain coordination; they are not validated motion planning or collision-avoidance software.

## One loop, with two different kinds of message

An **observation** says what was measured: “Zone A soil moisture was 0.218 m³/m³ at this time.” A **command** requests a bounded change: “Open valve A for at most 120 seconds, if the command is still valid.” They need different validation, permissions and failure handling.

A recommendation is not a command. Approval is not machine acceptance. Acceptance is not completion. Completion is not proof of the intended agricultural outcome. An operational implementation should preserve these distinct states and correlate all of them with the original evidence.

The return path matters: after an action, a new observation lets the operator compare the outcome with the prediction. A failure or stale input should remain visible; it should never be silently replaced with a successful animation.

## What adding a component means

- **Sensor:** declare an identifier, asset, measured property, unit and transport; map its native payload into a normalized observation.
- **Robot:** declare supported mission capabilities and operational limits; exchange missions, acknowledgements and status with its onboard controller.
- **Actuator:** declare permitted operations and bounds; implement acknowledgement, timeout and feedback locally.
- **Model:** declare required inputs, parameters, validity limits, output units and a version; expose a predictable calculation interface.

The browser onboarding demonstrates this registration idea. Connecting real hardware additionally requires an adapter, identity provisioning and an operational backend. Exported example manifests are starting points for integration design.

## Deployment boundary

This static package runs the visualization and simulation in the visitor's browser. A production AGRIOS deployment would additionally need a registry, message transport, storage, validation, authorization, an audit trail, service monitoring and hardware adapters. The original concept's marketplace, API gateway, knowledge graph and multi-site infrastructure are architecture goals, not hidden services delivered by this ZIP.

Robot motion control, emergency stopping and local protective functions remain on the robot or certified control system. An AGRIOS supervisory connection must not become a prerequisite for stopping safely. A browser animation or emergency-stop button is not a physical safety system.

See `INTEGRATION_GUIDE.md` for proposed message examples and a practical path from demonstration to a hardware pilot.