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.
2. env/environment.py resets the episode and initializes seeded runtime state.
3. 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 resolves execution uncertainty, introducing controlled stochastic outcomes.
6. env/reward.py computes dense step rewards.
7. 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 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.