# amprex: Smart Energy Management System (EMS)

amprex (engineered internally under the KSoft EMS project name) is a next-generation, high-performance smart energy management system designed for physical hardware deployments (such as Raspberry Pi 5 with NVMe storage) and cloud control. It maximizes energy efficiency, provides forecast-driven battery (BESS), EV charging, and HVAC optimization, preserves privacy, and integrates seamlessly with local devices and global utility grid rates.

## Key Features

- **Directional Telemetry Signage**: Directional keys (`_IMPORT`, `_EXPORT`, `_CHARGE`, `_DISCHARGE`) are always non-negative (`>= 0`). Cumulative keys (`_TOTAL`) are signed: positive values represent import/charge, negative values represent export/discharge.
- **Forecast-Driven Optimization**: Incorporates weather and grid tariff scheduling using `TariffScheduleRuleEntity` daily windows in JSON (`time_ranges`).
- **License Gating**:
  - **LITE**: Standard monitoring, basic local forecasts, configuration for up to 5 devices, basic HVAC control.
  - **PLUS**: Local on-device ML forecasts, advanced HVAC smart mode, unlimited standard device integrations.
  - **PRO / INDUSTRIAL**: Advanced cloud ML+AI predictive forecasts, full industrial and grid telemetry tracking.

## Developer & Agent Integration

amprex is fully optimized for programmatic access and agentic integration.

### Machine-Readable Resources

- **API Catalog**: [/.well-known/api-catalog](https://amprex.app/.well-known/api-catalog) - Links together REST and MCP.
- **OpenAPI Schema**: [https://api.amprex.app/openapi.json](https://api.amprex.app/openapi.json) - Complete REST documentation.
- **MCP Server Card**: [/.well-known/mcp/server-card.json](https://amprex.app/.well-known/mcp/server-card.json) - Model Context Protocol tool definitions.

### Cloud REST & MCP API Endpoints
All API calls are relative to the base URL `https://api.amprex.app`. MCP is served via FastMCP Streamable HTTP at `https://api.amprex.app/mcp`.

#### Core Tools & Operations
- `list_controllers`: Returns a list of amprex controllers accessible under the client's token.
- `get_controller`: Returns metadata for a specified controller.
- `read_site_parameters`: Reads latitude, longitude, timezone, grid import/export limits, and physical line fuse limits.
- `query_telemetry`: Fetches aggregated electrical and device-level telemetry. Window aggregates (`5m`, `15m`, `1h`, `6h`, `12h`, `daily`) are strictly enforced for database efficiency.
- `query_control`: Queries historical optimization plan targets and commanded battery/HVAC states.
- `read_forecasts`: Retrieves solar and load forecast data blocks.
- `read_strategy`: Obtains the near-term and strategic battery optimization plans.
- `read_tariffs`: Retrieves currently active grid tariff rate schedules.
- `alert_summary`: Consumes warning, info, and critical active alarms or system health watchdogs.

## Dynamic Markdown Landing Page

A complete markdown representation of the amprex homepage is available at:
- [Landing Page (Markdown)](https://amprex.app/index.md)