docs/ARCHITECTURE.md

# Architecture

SYNAPSE-X models decision-making as a balance between risk, uncertainty, and reward over time.

The structure keeps the system easy to inspect while preserving meaningful decision complexity.

SYNAPSE-X is organized as a small benchmark stack with clear boundaries between environment logic, agents, serving, and evaluation.

## Component Map

| Area | Responsibility |
| --- | --- |
| `env/` | core environment mechanics, predictive features, reward shaping, and deterministic grading |
| `agents/` | reusable policies for comparison and benchmarking |
| `api/` | FastAPI application that exposes the benchmark over HTTP |
| `scripts/` | runnable entrypoints for verification, benchmarking, reporting, and inference |
| `configs/` | lightweight configuration values and metadata |
| `docs/` | submission-facing narrative and technical notes |

## Core Runtime Flow

1. A task preset is selected from [env/grader.py](../env/grader.py).
2. [env/environment.py](../env/environment.py) resets the episode and initializes seeded runtime state.
3. [env/echo.py](../env/echo.py) enriches each task with predictive signals: `future_risk` and `deadline_pressure`.
4. An agent selects `execute`, `delay`, or `reallocate` using current and predictive state.
5. [env/prism.py](../env/prism.py) resolves execution uncertainty, introducing controlled stochastic outcomes.
6. [env/reward.py](../env/reward.py) computes dense step rewards.
7. [env/grader.py](../env/grader.py) converts the resulting action trace into a deterministic final score.

## System Flow

`STATE -> ECHO -> AGENT -> PRISM -> REWARD -> GRADER`

## CASCADE-X Crisis Dynamics

Hard mode adds dependency propagation and a nonlinear crisis transition on top of the base scheduler.

- `system_pressure` is normalized before it is fed into risk, deadline, and phase calculations
- the normalized pressure signal is bounded to `(0, 1)`, which keeps downstream tooling and metrics stable
- once normalized pressure crosses the phase threshold of `0.75`, the environment enters a nonlinear crisis regime
- `reallocate` restores at most `0.2` resources per step, which intentionally limits recovery speed during crisis handling

## Environment Contract

### Observation

Each observation contains:

- `tasks`: sorted task list
- `time`: current timestep
- `resources`: current resource pool
- `episode_done`: terminal flag

Each task includes priority, risk, uncertainty, deadline, resource cost, completion state, and the predictive fields produced by `ECHO`.

### Actions

The environment accepts a compact action interface:

- `execute(task_id)`
- `delay(task_id)`
- `reallocate(task_id)`

This keeps the API simple while still forcing meaningful strategy choices.

The `reallocate` action has a hard resource-recovery cap of `0.2` per step.

## API Surface

The local API in [api/app.py](../api/app.py) exposes the benchmark in a submission-friendly way:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/health` | `GET` | confirm server availability |
| `/reset` | `GET`, `POST` | start a new episode |
| `/step` | `POST` | apply one action |
| `/state` | `GET` | inspect current state |
| `/tasks` | `GET` | enumerate task presets |
| `/grade` | `POST` | score an action trace |

## Design Guarantees

- reproducibility: stochastic execution is seed-controlled
- stability: rewards are clamped and observations are sorted
- clarity: evaluation logic is separated from deployment and agent code
- portability: the same benchmark can run locally, through the API, or via Docker

## Why This Structure Works

- judges can inspect environment logic without reading serving code
- baseline and comparison agents are easy to run side by side
- benchmark verification is a single script instead of a manual checklist
- the repository stays focused on the benchmark rather than optional product layers

## Summary

SYNAPSE-X separates prediction (ECHO), uncertainty (PRISM), and evaluation (grader) to produce a reproducible, interpretable benchmark for strategic decision-making.