CoolFace
Apppublic

Angshuman28/ampere-hf-backend

sourceHugging Facemitupdated 4mo agoView on Hugging Face
0likes
App README

AMPERE HF Space Backend (Phase B Skeleton)

Minimal FastAPI backend that wraps the Phase A inference bundle (outputs/inference_bundle/appliance_8ch/ in the research repo, duplicated under models/appliance_8ch/ here) and exposes:

MethodPathStatus
GET/healthimplemented
GET/readyimplemented
GET/versionimplemented
POST/reconstructimplemented (runs the DwellObserver-T forward pass)
GET/device/{device_id}/stateimplemented
POST/device/resetimplemented (admin-token gated when set)
POST/schedule/nextimplemented (learned-heuristic, NOT RL)
GET/recommendations/{device_id}implemented (rule-based)

This is Phase B. It is intended to live inside the research repo for now; the directory can be lifted out and pushed to a Hugging Face Space once the encoder has been golden-tested (see app/inference/encoder.py for the TODO).

Layout

ampere-hf-space/
  app/                          FastAPI app + routes + inference glue
    main.py                     create_app(), lifespan loads the bundle
    schemas.py                  Pydantic request/response models
    routes/                     One module per endpoint
    inference/                  bundle.py, encoder.py, runner.py, ...
    state/device_state.py       Per-device ring buffer + EWMA stats
    recommendations/rules.py    Day-1 rule engine
    scheduler/adaptive.py       Day-1 balanced_transition_change policy
    util/                       config, logging, executor helpers
  ampere_lib/                   Vendored minimal slice of ampere.neural
    neural/observer_models.py   DwellObserver architecture (verbatim)
    neural/dwell_dataset.py     DwellNormalizer
    neural/utils.py             require_torch + resolve_device
  models/appliance_8ch/         Bundle copied from outputs/inference_bundle/
  tests/                        pytest + TestClient
  README.md
  requirements.txt
  pyproject.toml

Running locally

bash
# from this directory
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 7860

Environment variables:

VariableDefaultPurpose
AMPERE_MODEL_DIRmodels/appliance_8chBundle directory; can be absolute
AMPERE_DEVICEautocpu, cuda, or auto
AMPERE_LOG_LEVELINFORoot logger level
AMPERE_CORS_ALLOW_ORIGINS*CSV of allowed origins
AMPERE_ADMIN_TOKENunsetWhen set, /device/reset requires Authorization: Bearer <token>
AMPERE_INFERENCE_THREADS1Worker pool size (Phase B uses sync forward)

No Turso, no Hugging Face, no third-party tokens are read. Secrets stay outside this Space.

Quick smoke

bash
curl -s http://localhost:7860/health
curl -s http://localhost:7860/version

curl -s -X POST http://localhost:7860/reconstruct \
  -H "Content-Type: application/json" \
  -d '{"device_id":"home-01","timestamp":"2026-05-13T15:30:25Z",
       "selected_branch_id":3,"observed_power_w":1247.3,"dwell_seconds":0.96}'

curl -s -X POST http://localhost:7860/schedule/next \
  -H "Content-Type: application/json" \
  -d '{"device_id":"home-01","current_time":"2026-05-13T15:30:25Z"}'

curl -s http://localhost:7860/recommendations/home-01

Running the tests

bash
python -m pytest -q

Tests cover: health, bundle loading, encoder shape/finiteness, the reconstruct flow end-to-end, device state, the recommendation engine, and the adaptive scheduler.

Phase B golden-parity TODO

app/inference/encoder.py rebuilds the 23 features documented in the bundle's feature_contract.json, but does not golden-test against the research repo's DwellWindowDataset.__getitem__. See the module docstring for details and the explicit follow-up before this skeleton ships to production.

What this backend does NOT do (Phase B scope)

  • —No deployment to Hugging Face Spaces yet.
  • —No Turso writes (Flutter owns the durable layer).
  • —No Flutter or Digital Twin edits.
  • —No RL scheduler (Day-2 will add a separate service).
  • —No model retraining.
  • —No user auth beyond an optional admin token on /device/reset.
  • —No background jobs.