JevPlays/ASSUMPTIONS.md

Design Decisions & Recorded Assumptions

This document records the architectural choices, default parameters, and operational assumptions made during the design and implementation of JevPlayer.

---

1. TypeSafe Jev API & Spend Economics

• API Endpoint & Protocol:
  • Default URL: https://api.typesafe.ai/v1/systemone
  • Protocol: HTTP/2 with persistent connection pooling and TLS session resumption.
  • Authentication: Bearer token via Authorization: Bearer <key>.
  • Environment Fallback: TYPESAFE_AI_API_KEY is checked if the config field apiKey is empty.
• Model Cost & Spend Cap:
  • Standard pricing model: $0.042 per 1M input tokens.
  • Token estimation rule: 1 token \approx 4 characters of JSON snapshot prompt.
  • Spend Cap Default: $1.00 per episode run.
  • Hard Cap Behavior: When cumulative estimated spend reaches spendCapUsd, the system logs a SpendCapExceededEvent and transitions seamlessly to MockProvider (heuristic fallback) without throwing runtime exceptions or crashing Minecraft.
• Confidence Calibration:
  • Default Confidence Threshold: 0.65.
  • Any decision returned with confidence < 0.65 triggers the fallback selector (selecting the highest confidence option that satisfies current immediate needs such as low health or urgent shelter).

---

2. Multi-Threading & Concurrency Model

• Client Thread Protection:
  • Minecraft's main client render thread must never block on network I/O.
  • All calls to DecisionProvider.query() run asynchronously in a dedicated cached executor thread pool.
  • Target per-tick client overhead: < 0.3 \text{ ms} average, with a hard budget of < 2.0 \text{ ms} for worst-case spikes.
• State & Decision Synchronization:
  • Synchronization between the main tick thread and the decision background thread is managed via non-blocking AtomicReference<StateSnapshot> and AtomicReference<JevDecision>.
  • While a network query is in-flight (typically 70–500 ms), the bot continues executing its active Baritone goal or holds state.
• Preemptive Reflex Engine:
  • Synchronous reflex evaluations execute every tick prior to accepting any Jev decision.
  • If an emergency is detected (lava submersion, drowning/air < 4, burning without water, point-blank hostile damage, starvation \le 2 food), reflexes immediately seize control, execute protective actions (e.g. step back, swim up, eat food, sprint dodge), and cancel any obsolete asynchronous goal.

---

3. Baritone Integration & Actuation

• API Boundary & Licensing:
  • Strictly binds to baritone.api.BaritoneAPI via public interfaces.
  • Zero forking and zero bundling of Baritone source code, fully respecting the LGPL-3.0 license.
  • Baritone is loaded as a runtime mod (modCompileOnly during build).
• Legitimacy & Fair Mode:
  • fairMode=true by default: sets BaritoneAPI.getSettings().legitMine.value = true. The bot only pathfinds to and mines blocks that have been exposed to player sight or are logically discoverable without X-Ray cheats.
  • smoothLook=true by default: activates cinematic camera interpolation so video recordings appear organic rather than jerky or robotic.
  • allowSprint=true: enables tactical sprinting during pathfinding and combat flees.
• Nether Pathfinding:
  • Includes dev.babbaj:nether-pathfinder:1.6 runtime capability for dimension transitions.

---

4. Safety, Watchdogs & Controls

• Singleplayer Restriction:
  • Automation bots on public servers violate multiplayer fair-play rules.
  • allowMultiplayer=false is enforced by default. If the player connects to an external multiplayer server, the mod logs a warning and disables autonomous ticking unless the user explicitly overrides allowMultiplayer: true in jevplayer.json.
• Instant Kill Switch:
  • Keybinding: F9 (default MISC category).
  • Pressing F9 immediately sets the internal state to DISABLED, cancels all active Baritone processes (getCustomGoalProcess().isActive(), getPathingBehavior().cancelEverything()), and halts background polling.
• Watchdog Escalation:
  • Stuck Watchdog: Triggers if player position has moved < 1.5 blocks over a 45-second sliding window while no inventory changes have occurred. Clears pathing cache, jumps/steps aside, and resets goal.
  • Loop Breaker: Triggers if the same high-level action fails 3 consecutive times. Blacklists that specific action for 60 seconds to prevent getting trapped in local minima.
  • Death Watchdog: Detects player death, records the milestone failure, awaits respawn, and resets the goal planner to Phase 1 (gather wood).

---

5. Security & Privacy

• Zero API Key Leakage:
  • The API key is never serialized into plain text in episode_events.json, decision_log.jsonl, standard Minecraft logs, or rendered on the HUD overlay.
  • The method JevPlayerConfig.getRedactedApiKey() masks all but the first 7 and last 4 characters (sk-live_***abcd).
  • No secret keys are stored in version control; .gitignore guards all environment and secret files.

---

6. HUD & Video Overlay

• In-Game Overlay:
  • Keybinding: F8 toggles HUD display on/off.
  • Visuals: Clean semi-transparent card rendering current milestone, active Jev action, decision confidence percentage, rolling latency (p50/p95), watchdog state, and cumulative token spend.
  • Rendering Throttling: State text formatting is throttled to update at most once every 200 ms to prevent per-frame garbage generation.