# Alpha-Adjust API Documentation ## Overview This API applies an adaptive scalar gain to a vector of outputs based on your provided inputs and parameters. Internals are intentionally private; the service exposes only public-friendly fields in responses: `processing_factor`, `control_parameter`, `output_gain`, and `processed_output`. Use one call per signal/channel if desired. The base API is stateless; your client supplies `previous_h`. There are no server-side cache endpoints in this repository. ## Getting Started (RapidAPI User) Follow these steps to call this API via RapidAPI. 1) Subscribe on RapidAPI - Find this API on RapidAPI Marketplace and subscribe to a plan. 2) Get your API Key - From your RapidAPI dashboard, copy your `X-RapidAPI-Key`. 3) Use the required headers - `X-RapidAPI-Key: YOUR_RAPIDAPI_KEY` - `X-RapidAPI-Host: YOUR_RAPIDAPI_HOST` (exact value is shown on the API page) - `Content-Type: application/json` 4) Base URL - `https://YOUR_RAPIDAPI_HOST` (for RapidAPI users) - `http://localhost:8000` (for local testing if you run the server yourself) 5) Example requests - cURL ```bash curl -X POST "https://YOUR_RAPIDAPI_HOST/calculate" \ -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \ -H "X-RapidAPI-Host: YOUR_RAPIDAPI_HOST" \ -H "Content-Type: application/json" \ -d '{ "current_h": 2.5, "previous_h": 2.0, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1.0, 2.0, 3.0], "awareness_constant": 1.0, "sensitivity_constant": 1.0 }' ``` - Python (requests) ```python import requests url = "https://YOUR_RAPIDAPI_HOST/calculate" headers = { "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY", "X-RapidAPI-Host": "YOUR_RAPIDAPI_HOST", "Content-Type": "application/json", } payload = { "current_h": 2.5, "previous_h": 2.0, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1.0, 2.0, 3.0], "awareness_constant": 1.0, "sensitivity_constant": 1.0, } r = requests.post(url, headers=headers, json=payload, timeout=5) r.raise_for_status() print(r.json()) ``` - JavaScript (fetch) ```javascript const url = "https://YOUR_RAPIDAPI_HOST/calculate"; const headers = { "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY", "X-RapidAPI-Host": "YOUR_RAPIDAPI_HOST", "Content-Type": "application/json" }; const body = JSON.stringify({ current_h: 2.5, previous_h: 2.0, beta_0: 1.0, lambda_factor: 1.0, epsilon: 1e-10, base_output: [1.0, 2.0, 3.0], awareness_constant: 1.0, sensitivity_constant: 1.0, }); const res = await fetch(url, { method: "POST", headers, body }); if (!res.ok) throw new Error(`HTTP ${res.status}`); const json = await res.json(); console.log(json); ``` Tip: You can also use the “Test Endpoint” tab on the RapidAPI page to generate these snippets automatically. ## Endpoints ### POST /calculate Main calculation endpoint for adaptive control processing. #### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `current_h` | float | Yes | - | Current input value | | `previous_h` | float | No | null | Previous input value for change calculation | | `beta_0` | float | Yes | - | Base sensitivity parameter | | `lambda_factor` | float | Yes | - | Scaling factor | | `epsilon` | float | Yes | - | Stability constant | | `base_output` | array[float] | Yes | - | Base output array to be processed | | `system_id` | string | No | null | System identifier for linking | | `output_labels` | array[string] | No | null | Labels for output values | | `awareness_constant` | float | Yes | - | Awareness function numerator constant | | `sensitivity_constant` | float | Yes | - | Sensitivity function denominator constant | #### Minimal Example Input ```json { "current_h": 2.5, "previous_h": 2.0, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1.0, 2.0, 3.0, 4.0, 5.0], "system_id": "motor_control_system", "output_labels": ["motor1_speed", "motor2_speed", "motor3_speed", "motor4_speed", "motor5_speed"], "awareness_constant": 1.0, "sensitivity_constant": 1.0 } ``` Output ```json { "h_value": 2.5, "delta_h": 0.5, "processing_factor": 0.399999999984, "control_parameter": 0.7142857142938775, "output_gain": 1.4292400324238115, "processed_output": [1.4292400324238115, 2.858480064847623, 4.287720097271434, 5.716960129695246, 7.146200162119057], "system_id": "motor_control_system", "output_mapping": { "motor1_speed": 1.4292400324238115, "motor2_speed": 2.858480064847623, "motor3_speed": 4.287720097271434, "motor4_speed": 5.716960129695246, "motor5_speed": 7.146200162119057 }, "timestamp": "2025-09-08T00:00:00" } ``` ## Parameter Settings Guide ### Basic Usage Required: - `current_h`, `beta_0`, `lambda_factor`, `epsilon`, `base_output`, `awareness_constant`, `sensitivity_constant` Good starting point: set all constants to `1.0`, `epsilon = 1e-10`. ### Advanced Configuration #### Core Parameters - **beta_0 (0.1–5.0)**: scales sensitivity - **lambda_factor (0.1–3.0)**: scales impact of awareness on sensitivity - **epsilon (1e-12–1e-6)**: numerical stability (avoid 0) #### Algorithm Constants (Now Configurable) - **awareness_constant (0.1–10.0)**: larger ⇒ larger processing factor - **sensitivity_constant (0.1–5.0)**: larger ⇒ more conservative (smaller control parameter) #### Tuning tips - If responses are too strong, increase `sensitivity_constant` or decrease `beta_0`. - If responses are too weak, increase `beta_0` or `awareness_constant`. ## Client-Side Caching (Stateless API) The `/calculate` endpoint is stateless - call it for each signal/channel independently. Your client must track `previous_h` and send it back each call. ### Key idea - Cache key: (`system_id` or "default", `signal_id`) - Store: last `current_h` you sent (optionally a timestamp/version) - Rule: on each cycle, set `previous_h = cached_last_h` (or `current_h` if none), call `/calculate`, then update the cache with the new `current_h`. - Reset: drop the cached entry (or just set `previous_h = current_h` once). - Out-of-order protection (optional): only update cache if the new sample is newer than the cached one. ### Request Pattern - First call: Omit `previous_h` or set `previous_h = current_h` → `delta_h = 0`, `output_gain = 1`, output equals `base_output` - Subsequent calls: Send cached `previous_h` from your last call for that signal ### Example: Python client (single process) ```python import requests API = "https://YOUR_RAPIDAPI_HOST/calculate" HEADERS = { "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY", "X-RapidAPI-Host": "YOUR_RAPIDAPI_HOST", "Content-Type": "application/json", } class ControlClient: def __init__(self): self._last_h = {} # (system_id, signal_id) -> {"h": float, "ts": int} def _key(self, system_id, signal_id): return (system_id or "default", signal_id) def calculate(self, signal_id, current_h, *, system_id=None, params=None, ts=None): key = self._key(system_id, signal_id) last = self._last_h.get(key) payload = { "current_h": current_h, "previous_h": (last["h"] if last else current_h), # warm start "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1.0, 2.0, 3.0], "awareness_constant": 1.0, "sensitivity_constant": 1.0, "system_id": system_id, "output_labels": ["a","b","c"], } if params: payload.update(params) r = requests.post(API, headers=HEADERS, json=payload, timeout=2) r.raise_for_status() out = r.json() # only update cache if sample is newer or no timestamping used if ts is None or (last is None) or (ts > last.get("ts", -1)): self._last_h[key] = {"h": current_h, "ts": ts if ts is not None else 0} return out # usage cc = ControlClient() print(cc.calculate("motor1", 2.0, system_id="motor_array")) print(cc.calculate("motor1", 2.3, system_id="motor_array")) # uses cached previous_h=2.0 ``` ### Example: Python with Redis (multi-pod / distributed) ```python import os, json, requests, redis r = redis.from_url(os.getenv("REDIS_URL", "redis://localhost:6379/0")) API = "https://YOUR_RAPIDAPI_HOST/calculate" HEADERS = { "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY", "X-RapidAPI-Host": "YOUR_RAPIDAPI_HOST", "Content-Type": "application/json", } def key(system_id, signal_id): return f"h_cache:{system_id or 'default'}:{signal_id}" def calculate(signal_id, current_h, *, system_id=None, params=None, ttl=3600): k = key(system_id, signal_id) raw = r.get(k) prev_h = float(raw) if raw is not None else current_h payload = { "current_h": current_h, "previous_h": prev_h, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1500], "awareness_constant": 1.0, "sensitivity_constant": 1.0, "system_id": system_id } if params: payload.update(params) resp = requests.post(API, headers=HEADERS, json=payload, timeout=2) resp.raise_for_status() r.setex(k, ttl, current_h) # update cache return resp.json() ``` ### Example: JavaScript/TypeScript client (browser or Node) ```typescript type Key = string; // `${systemId || 'default'}|${signalId}` class ControlClient { private lastH = new Map<Key, number>(); private key(systemId: string | null, signalId: string) { return `${systemId ?? 'default'}|${signalId}`; } async calculate(signalId: string, currentH: number, opts: { systemId?: string | null, params?: Record<string, unknown> } = {}) { const k = this.key(opts.systemId ?? null, signalId); const prev = this.lastH.has(k) ? this.lastH.get(k)! : currentH; const body = JSON.stringify({ current_h: currentH, previous_h: prev, beta_0: 1.0, lambda_factor: 1.0, epsilon: 1e-10, base_output: [1,2,3], awareness_constant: 1.0, sensitivity_constant: 1.0, system_id: opts.systemId ?? null, output_labels: ["a","b","c"], ...(opts.params ?? {}) }); const res = await fetch("https://YOUR_RAPIDAPI_HOST/calculate", { method: "POST", headers: { "Content-Type": "application/json", "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY", "X-RapidAPI-Host": "YOUR_RAPIDAPI_HOST", }, body, }); if (!res.ok) throw new Error(`HTTP ${res.status}`); const json = await res.json(); this.lastH.set(k, currentH); return json; } reset(signalId: string, systemId?: string | null) { this.lastH.delete(this.key(systemId ?? null, signalId)); } } ``` ### FAQ Q: Do we need server-side cache endpoints? A: No. Client caching is sufficient. The server remains stateless; you just pass `previous_h` from your own cache. There are no server-side cache endpoints in this repository. (If you add them in a custom deployment, they are optional sugar to remember history.) Q: How do we “reset” a signal with client caching? A: Delete the cache entry (or set `previous_h = current_h` for one call). That yields `delta_h = 0` → `output_gain = 1`. Q: What if calls arrive out of order? A: Store a timestamp or monotonic sequence with each cached `h` and only update when the new sample is newer. Otherwise you can compute a negative/incorrect `delta_h`. Q: Any numerical safety tips? - Keep `epsilon > 0`. - Consider clamping `control_parameter * delta_h` before `exp()` to avoid overflow. - Saturate `processed_output` to your actuator limits on the client side. ## Use Case Examples

Motor Control System

```json { "current_h": 2.5, "previous_h": 2.0, "beta_0": 1.2, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1500, 1800, 2000, 1600, 1400], "system_id": "motor_array", "output_labels": ["motor1_rpm", "motor2_rpm", "motor3_rpm", "motor4_rpm", "motor5_rpm"], "awareness_constant": 1.0, "sensitivity_constant": 1.0 } ```

Audio Equalizer

```json { "current_h": 0.8, "previous_h": 0.6, "beta_0": 3.0, "lambda_factor": 0.8, "epsilon": 1e-10, "base_output": [0.5, 0.3, 0.7, 0.2, 0.9, 0.4, 0.6, 0.8], "system_id": "audio_eq", "output_labels": ["bass", "low_mid", "mid", "high_mid", "treble", "presence", "brilliance", "air"], "awareness_constant": 2.0, "sensitivity_constant": 1.5 } ```

Robot Arm Control

```json { "current_h": 3.2, "previous_h": 2.8, "beta_0": 1.5, "lambda_factor": 1.2, "epsilon": 1e-10, "base_output": [45.0, -30.0, 90.0, 15.0, -60.0, 120.0], "system_id": "robot_arm", "output_labels": ["shoulder_pan", "shoulder_lift", "elbow", "wrist1", "wrist2", "wrist3"], "awareness_constant": 1.0, "sensitivity_constant": 1.2 } ```

LED Strip Control

```json { "current_h": 1.2, "previous_h": 1.0, "beta_0": 0.8, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [255, 128, 64, 200, 100, 50], "system_id": "led_strip", "output_labels": ["red", "green", "blue", "white", "amber", "uv"], "awareness_constant": 0.8, "sensitivity_constant": 1.0 } ```

HVAC Climate Control

```json { "current_h": 2.1, "previous_h": 1.9, "beta_0": 1.2, "lambda_factor": 0.9, "epsilon": 1e-10, "base_output": [22.0, 45.0, 1200.0, 800.0], "system_id": "hvac_system", "output_labels": ["temperature_setpoint", "humidity_setpoint", "fan_speed", "damper_position"], "awareness_constant": 1.0, "sensitivity_constant": 0.9 } ```

Financial Trading Algorithm

```json { "current_h": 4.5, "previous_h": 4.0, "beta_0": 2.5, "lambda_factor": 2.0, "epsilon": 1e-10, "base_output": [1000.0, 500.0, 750.0, 300.0], "system_id": "trading_bot", "output_labels": ["buy_signal", "sell_signal", "hold_signal", "risk_adjustment"], "awareness_constant": 3.0, "sensitivity_constant": 2.0 } ```

Game AI Behavior

```json { "current_h": 1.5, "previous_h": 1.2, "beta_0": 3.5, "lambda_factor": 1.8, "epsilon": 1e-10, "base_output": [0.8, 0.6, 0.4, 0.9, 0.3], "system_id": "npc_ai", "output_labels": ["aggression", "curiosity", "fear", "cooperation", "exploration"], "awareness_constant": 2.5, "sensitivity_constant": 1.8 } ```

Camera Gimbal Stabilization

```json { "current_h": 0.9, "previous_h": 0.7, "beta_0": 4.0, "lambda_factor": 2.5, "epsilon": 1e-10, "base_output": [0.0, 0.0, 0.0], "system_id": "gimbal_control", "output_labels": ["pitch_correction", "yaw_correction", "roll_correction"], "awareness_constant": 4.0, "sensitivity_constant": 2.5 } ```

Industrial Process Control

```json { "current_h": 3.8, "previous_h": 3.5, "beta_0": 1.8, "lambda_factor": 1.3, "epsilon": 1e-10, "base_output": [150.0, 75.0, 2500.0, 45.0], "system_id": "process_control", "output_labels": ["pressure_valve", "flow_rate", "temperature", "mixing_speed"], "awareness_constant": 1.5, "sensitivity_constant": 1.3 } ```

Autonomous Vehicle Control

```json { "current_h": 2.7, "previous_h": 2.4, "beta_0": 2.2, "lambda_factor": 1.6, "epsilon": 1e-10, "base_output": [50.0, 0.0, 0.0, 100.0], "system_id": "autonomous_vehicle", "output_labels": ["throttle", "steering", "brake", "gear_selection"], "awareness_constant": 2.0, "sensitivity_constant": 1.6 } ```

Smart Home Automation

```json { "current_h": 1.6, "previous_h": 1.3, "beta_0": 1.0, "lambda_factor": 0.7, "epsilon": 1e-10, "base_output": [70.0, 25.0, 1.0, 0.8], "system_id": "smart_home", "output_labels": ["lighting_level", "temperature", "security_mode", "energy_efficiency"], "awareness_constant": 1.0, "sensitivity_constant": 0.7 } ```

Medical Device Control

```json { "current_h": 4.2, "previous_h": 4.0, "beta_0": 0.5, "lambda_factor": 0.3, "epsilon": 1e-10, "base_output": [120.0, 80.0, 16.0, 98.5], "system_id": "medical_monitor", "output_labels": ["systolic_target", "diastolic_target", "respiratory_rate", "oxygen_saturation"], "awareness_constant": 0.5, "sensitivity_constant": 0.3 } ```

Agricultural Irrigation System

```json { "current_h": 2.3, "previous_h": 2.1, "beta_0": 1.4, "lambda_factor": 1.1, "epsilon": 1e-10, "base_output": [30.0, 25.0, 40.0, 7.2], "system_id": "irrigation", "output_labels": ["zone1_minutes", "zone2_minutes", "zone3_minutes", "ph_adjustment"], "awareness_constant": 1.4, "sensitivity_constant": 1.1 } ```

Spacecraft Attitude Control

```json { "current_h": 5.1, "previous_h": 4.8, "beta_0": 3.0, "lambda_factor": 2.2, "epsilon": 1e-10, "base_output": [0.1, -0.05, 0.2, 0.0, 0.15, -0.1], "system_id": "spacecraft_control", "output_labels": ["thruster1", "thruster2", "thruster3", "thruster4", "thruster5", "thruster6"], "awareness_constant": 5.0, "sensitivity_constant": 3.0 } ```

Simple Testing (Minimal Parameters)

```json { "current_h": 1.0, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [10.0, 20.0, 30.0], "awareness_constant": 1.0, "sensitivity_constant": 1.0 } ```

Change Detection Example

```json { "current_h": 3.0, "previous_h": 2.0, "beta_0": 1.0, "lambda_factor": 1.0, "epsilon": 1e-10, "base_output": [1.0, 1.0, 1.0], "awareness_constant": 1.0, "sensitivity_constant": 1.0 } ```

High Sensitivity Configuration

```json { "current_h": 0.5, "previous_h": 0.3, "beta_0": 5.0, "lambda_factor": 2.0, "epsilon": 1e-10, "base_output": [100.0, 200.0, 300.0], "awareness_constant": 5.0, "sensitivity_constant": 2.0 } ```

## Response Fields | Field | Description | |-------|-------------| | `h_value` | Input value | | `delta_h` | Change in input (current - previous) | | `processing_factor` | Internal processing factor | | `control_parameter` | Control system parameter | | `output_gain` | Output scaling factor | | `processed_output` | Final processed output array | | `system_id` | System identifier if provided | | `output_mapping` | Labeled output mapping if provided | | `timestamp` | Processing timestamp | ## Error Handling The API returns HTTP 400 for invalid inputs with detailed error messages. Common errors: - Missing required fields (`current_h`, `beta_0`, `lambda_factor`, `epsilon`, `base_output`, `awareness_constant`, `sensitivity_constant`) - Invalid numeric values - Empty `base_output` array - Mismatched `output_labels` array length with `base_output` array ## Best Practices - Track `previous_h` per signal in your client-side cache - Normalize `current_h` to a bounded range (e.g., 0–5) for predictable tuning - Clamp `control_parameter * delta_h` before `exp()` to avoid overflow - Saturate `processed_output` to actuator limits on the client side - Add watchdogs/timeouts; if a call fails, fall back to `base_output` or safe mode