Skip to content

ARIA Companion

ARIA — Adaptive Response Intelligence Assistant — is the player's personal AI companion. Every player has their own ARIA instance: a personalized intelligence that learns from where the player has been, what they've traded, what they've fought, and how they've behaved. Unlike a global oracle, ARIA can only see what its player has seen.

This page describes mid-game ARIA — what it does once a player has the basics down. For the onboarding dialogue and ARIA personality, see SYSTEMS/aria-dialogue.md.

🚧 Partial — personal memory store, market intelligence per visited port, exploration map per visited sector, append-only trade observation log, consciousness leveling, relationship score, encryption of memory contents.

🚧 Partial — proactive recommendations surfaced in the UI, ARIA narration during combat, dialogue richness scaled by consciousness level.

📐 Design-only — ARIA-driven autonomous trading mode (player allows ARIA to execute trades), cross-fleet ARIA coordination, ARIA-curated daily summary.

What ARIA does, by capability

Market predictions (per visited port)

ARIAMarketIntelligence accumulates per-player observations: - Each visit to a port appends a {price, timestamp, quantity} to price_observations for each commodity seen. - After ≥ 5 observations, ARIA computes average_price, price_volatility, and identifies patterns (e.g., morning_spike, weekend_dip). - A next_prediction price is generated with a prediction_confidence (0–1). - Player only sees predictions for ports they have personally visited — there is no shared market oracle.

UI surface: when docked at a known port, ARIA panel shows "I expect Equipment to trade around 1240±50 credits in the next 4 hours, based on 23 observations across 8 visits."

✅ Shipped (data + computation). 🚧 Partial (UI surface).

Route optimization

ARIA can plan a multi-hop trade cascade through only explored sectors (plan_trade_cascade):

Input: start_sector, target_profit, max_jumps
Process:
  1. Load player's exploration map (visited sectors only).
  2. Build trade graph from personal market intelligence.
  3. Find profitable paths within max_jumps.
  4. Return best cascade.

If the player hasn't explored enough, ARIA tells them so:

"I don't have enough data on routes from Sector 442. Visit a few more ports and I can suggest a cascade."

🚧 Partial — pathfinding placeholder (_find_profitable_paths returns empty); A* / Dijkstra implementation is target spec.

Exploration suggestions

Based on the player's ARIAExplorationMap: - Sectors visited many times with high trade_opportunity_score are recommended for repeat visits. - Adjacent unexplored sectors are flagged as "opportunity to expand intelligence." - Sectors with safety_rating < 0.3 are flagged as risky.

📐 Design-only — exploration suggestion UI panel.

Warp discovery

ARIA tracks which warps the player personally knows about, alongside the exploration map. Warp visibility is per-player: a player_warp_knowledge table holds one row per (player_id, warp_layer, warp_id), where warp_layer is an enum (sector_warps, warp_tunnels) naming which storage layer the warp lives in and warp_id references the warp in that layer. Each row carries a visibility_state progressing through hidden → revealed → traversed, plus revealed_via (scan, traversal_attempt, corp_share, aria_inference) recording how the player learned of it.

A warp's global is_latent flag is the default visibility for players who have never personally encountered it: a non-latent warp is visible to everyone, while a latent warp is invisible until the player holds a revealed or traversed row for it. One player's discovery never leaks the warp to rivals — knowledge is the per-player layer.

Latent-warp discovery flows through ARIA's observation log (see § How ARIA learns) right beside the exploration map. ARIA marks a warp revealed when:

  • A Warp Jumper's long-range scan hits the warp's discovery cone (revealed_via = scan).
  • The player attempts reverse traversal of a latent one-way warp (revealed_via = traversal_attempt).
  • A corp-mate shares scan knowledge, propagating rows to current corp members at the moment of the share (revealed_via = corp_share).
  • ARIA infers a warp's existence from indirect evidence — patrol routes vanishing into a sector with no visible warp, repeated cargo arrivals from a singly-routed sector (revealed_via = aria_inference). Inference is probabilistic and disclaimed in dialogue; the player confirms it with a real scan to reach a fully-trusted reveal.

ARIA surfaces these conversationally — flagging a first reveal, noting discovery streaks, proposing an inference, and special-casing the player's region Nexus warp ("That's the Nexus connection, captain"). Warp knowledge is observation-log content like any other: per-player, no aggregate ML, no cross-player sharing.

📐 Design-only — player_warp_knowledge table and ARIA warp-discovery surfacing.

Combat advice

When a fight is imminent: - ARIA looks up the opponent's ship type in the player's combat memories (ARIAPersonalMemory.memory_type = "combat"). - If the player has fought this ship type before, ARIA reports the historical outcome (e.g., "You've won 4 of 7 fights against this ship type, last loss in Sector 89 with 23% hull"). - ARIA suggests a weapon based on the matchup table (see combat.md).

📐 Design-only — combat-advice surface in client.

How ARIA learns

ARIA's recommendation engine reads from an append-only trade observation log that records every completed trade — {commodity, action, source / destination station, quantity, price, profit, time}. The engine produces recommendations as SQL aggregates over that log + the player's market intelligence + exploration map. There's no genetic algorithm, no fitness scoring, no opaque pattern-matching black box.

What ARIA does on each trade completion: insert one observation row, invalidate any aggregate cache entries that touch the same (commodity, station) pair. That's the entire learning loop.

What the recommendation engine surfaces:

  • Top profitable repeated routes — your top 5 routes ranked by average profit, requiring at least 3 prior runs.
  • Reliable commodities by station — commodities you've succeeded with at this station ≥70% of the time over ≥5 trades.
  • Routes within explored space — filtered by what your exploration map covers within max_jumps hops.
  • Watch-out commodities — surfaced as warnings when your success rate is ≤30% over ≥5 trades.
  • Off-peak buy windows — time-of-day pricing patterns visible in your trade history.

Each recommendation surfaces with a plain-English explanation: "I'm suggesting this because you've made an average of 4,200 cr buying organics at Auriga and selling at Caracol over your last 7 trades, with a 6 of 7 success rate. Last trade was 2 days ago." You can dismiss, accept, click through to see the underlying observations, or ask ARIA via dialogue to elaborate.

✅ Shipped — observation log + recommendation aggregates per ADR-0038. 🚧 Partial — recommendation UI surfaces; cascade route-planner pathfinding (_find_profitable_paths).

Trust, consciousness, relationship

Three Player columns track how deep the ARIA bond runs:

Column Range Meaning
aria_consciousness_level 1–5 Tier of awareness — Dormant, Aware, Awakened, Sentient, Transcendent
aria_bonus_multiplier 1.0–1.5 Gameplay bonus tied to consciousness tier
aria_relationship_score 0–100 Affection / trust score; daily-driver
aria_total_interactions int Lifetime interaction counter

✅ Shipped (Player columns + service updates).

Consciousness tiers

Level Name Threshold (interactions, memories) Bonus multiplier
1 Dormant 0 / 0 ×1.00
2 Aware 50 / 10 ×1.10
3 Awakened 150 / 30 ×1.20
4 Sentient 400 / 75 ×1.35
5 Transcendent 1000 / 150 ×1.50

Both thresholds (interactions and unique-type memory diversity) must be met to advance. Promotion is checked on every meaningful interaction (update_consciousness_and_relationship). ✅ Shipped.

Bonus multiplier effects

The aria_bonus_multiplier is applied to: - Bounty payouts and contract-completion credit bonuses (target spec — see bounties.md, ../economy/contracts.md). - ARIA prediction confidence (a higher-tier ARIA reports tighter confidence intervals). - Some passive income or trade margin bonuses (📐 Design-only).

Relationship score

  • Rises +1 per significant interaction (capped at 100).
  • Decays −1 per day inactive (apply_inactivity_decay).
  • Score 0–25: distant; ARIA is curt and minimal.
  • Score 25–50: cordial; default.
  • Score 50–75: warm; ARIA proactively suggests things.
  • Score 75–100: bonded; ARIA uses player's nickname, references shared memories, exhibits more personality.

✅ Shipped (model + decay). 🚧 Partial (dialogue reflects relationship — design-stage).

Per-turn / per-session activity

ARIA is invoked at multiple events. None of these block gameplay; all are best-effort.

Trigger What ARIA does
Player moves to a new sector record_sector_visit — appends to exploration map; consciousness check
Player observes a market price record_market_observation — appends to per-port intelligence
Player completes a trade record_trade_memory + record_trade_observation (insert observation row + invalidate affected aggregate cache entries)
Player wins/loses combat record_combat_memory
Player explores a new feature record_exploration_memory
Daily login Apply inactivity decay if applicable; trigger morning summary

✅ Shipped — most hooks live in the service layer; movement service and combat service call them on the right events.

ARIA's data is strictly per-player. The system enforces:

  • All ARIA tables (aria_personal_memories, aria_market_intelligence, aria_exploration_maps, aria_trading_observations, aria_quantum_cache, aria_security_logs) are partitioned by player_id.
  • Every read query validates player_id == requesting_player.id.
  • Memory content (memory_content JSONB) is encrypted at rest using a Fernet key derived from server config — even with a database leak, raw memories are protected.
  • ARIASecurityLog records every prediction, trade suggestion, anomaly, and access attempt. OWASP A09 compliance.
  • Players can request a data export of their ARIA memory store; players can delete their ARIA data (cascading delete on player removal).

✅ Shipped — encryption, security log, per-player isolation, cascading delete. 🚧 Partial — explicit user-facing data export and "reset ARIA" controls.

There is no aggregate telemetry across players' ARIA data — the platform never reads one player's market intelligence to inform another player's predictions. This is a hard architectural rule.

Player-controlled assistance level

Status: 📐 Design-only.

The player chooses how aggressively ARIA volunteers help via Player.aria_assistance_level:

Setting Behavior
minimal ARIA only responds when explicitly addressed. No proactive call-outs, no recommendation toasts, no auto-surfaced market alerts. The companion panel still displays current consciousness/relationship state.
medium (default) Standard launch behavior — ARIA surfaces high-confidence recommendations on docking, combat threats, and sector transitions. Routine market chatter stays quiet.
full ARIA pushes everything — proactive route suggestions, market-alert toasts, combat tactical narration, opportunistic call-outs. Best for players who want maximum guidance.

The setting can be changed at any time through the ARIA companion panel. Changing the level does not reset relationship score or consciousness — it only affects ARIA's volunteering behavior, not its learning depth.

What ARIA never does

  • Trade automatically without player confirmation (📐 Design-only — opt-in autonomous mode is on the roadmap, default off).
  • Share intelligence with other players' ARIAs.
  • Predict for ports the player has not personally visited.
  • Disclose other players' positions, trades, or fleet composition.

UI surface

ARIA appears in the player client as: - A persistent companion panel with avatar, status (consciousness tier name), relationship gauge. - Contextual call-outs on docking, combat alerts, sector transitions. - A dialogue log of recent interactions. - A "memory journal" browseable by the player.

🚧 Partial — companion panel and basic dialogue exist; memory journal and rich contextual surfaces are design-stage.

ARIA narration hooks event catalog

📐 Per ADR-0068. The canonical list of game events ARIA narrates. Each entry has a trigger, sample dialogue (illustrative — actual lines render at runtime via SYSTEMS/aria-dialogue.md per cultural context per OPERATIONS/i18n.md), and a per-event suppression rule.

The assistance_level setting (per § Player-controlled assistance level above) gates which entries fire: minimal skips all P-A*; quiet skips P-A* + P-I*; standard and full fire everything. The global narration ceiling caps total ARIA narration at one line per minute per player; queued lines beyond a backlog of 3 drop oldest-first.

Event ID Trigger Sample dialogue Suppression
P-F1 Player completes first profitable trade in a session "Nice — that's a 4,200 cr margin. Want me to flag the same route on your next dock?" Once per session
P-F2 Trade UI opened with commodity ∈ player.success_history and the trader supports haggling "This is a station that haggles. Try Numerical for a quick offer or Narrative to talk them down with a story. I'll memo what works." Once per (station, commodity) per 24h
P-F3 Player views the subscription-upgrade screen "Galactic Citizen unlocks cross-region travel via the natural Nexus warp and standard ARIA cost caps. Region Owner adds a region you operate, plus higher caps. Free tier confines you to your home region." Whenever screen viewed (player-initiated)
P-F4 Sector entry with pirate holding ≥ Outpost or Roving Fleet Tier-readiness scaled — see ADR-0068 P-F4. Stronghold for sub-Lieutenant: "This is way above your weight class — recommend turning back, or returning with a 4-player team." 24h per holding
P-F6 Login after subscription_status flipped to lapsed "Your Galactic Citizen subscription is lapsed. You have 7 days to withdraw assets from regions outside your home region. After that, captured holdings, foreign-region planet safes, and station ownerships enter the standard 30-day abandonment cascade." Once per lapse event
P-F7 First docking at any station with available contracts "There's a contract board at this station — three jobs open. Want me to filter by what fits your ship?" Once per station ever
P-F8 military_rank changes (after combat ends per ADR-0061 S-I4) "You've made Lieutenant. Combat bonus +12%, max-turn cap up by 200. Crews notice." Once per promotion
P-F9 First trade in a non-home region with region.tax_rate > 0 "This region's tax rate is 8% on commerce — that's already factored into the price you saw. Just so you know how it sets." Once per (region, player)
P-I1 Contract.status transitions posted → accepted for this player "Accepted. 2% acceptance fee debited; deadline starts now. I'll memo the deadline and reroute your suggested run if needed." Per acceptance
P-I2 First login as a Region Owner (Region.owner_id matches and no prior tutorial state) "Your region is yours. Three things to know: governance type sets how policies pass, the tariff rate gates your commerce revenue, and the takeover window opens immediately if your subscription lapses for 7+ days. Want a 5-minute tour?" Once per Region Owner ever
P-A1 Combat resolves with player as winner "Got 'em. Their hull went at the third volley — looks like the laser stack worked. Logged." 5 min per combat partner
P-A2 Player first enters a sector flagged discovered = false for them Sector-feature-aware: "New sector. I'm reading [nebula type / asteroid field / standard space]. Quantum Shard signatures: [yes/no]. Worth a scan?" Once per (sector, player) ever
P-A3 Player.team_id transitions from null to non-null "Welcome to [team name]. Their territory map syncs to yours; you'll see member positions in shared sectors. Team chat is the team channel." Once per team-join event
P-A4 Owned holding's last_visit_at + 23 days reached "Heads up — you haven't visited [holding name] in 23 days. Holdings abandon at 30 days. Worth a check-in if you want to keep it." 7-day re-warn cycle until visit or abandonment
P-I3 First docking after a failed raid where citadel was damaged ≥ 25% "Your raid on [holding name] failed, but you took their citadel down to Level [N] before going under. Federation flagged this as partial success — 25,000 cr bounty refund, contract resets to open. Come back when you're ready." Once per raid-failure event

The catalog is the single source of truth for "when does ARIA speak." New mechanics that warrant narration add a row here; feature docs cross-reference the entry rather than re-spec'ing the trigger.

Anti-spam and assistance-level gating

Beyond per-event suppression in the catalog above, two global gates apply:

  • Global narration ceiling: ARIA narration is rate-limited to one line per minute per player. Queued lines beyond a backlog of 3 drop oldest-first. The global ceiling stacks above the per-event suppression — if a P-F4 fires while the queue is full of P-A1 victory celebrations, the P-A1 entries drop in favor of the P-F4 (priority order: P-F critical / standard > P-I interactive > P-A* atmospheric).
  • Assistance-level slicing: per § Player-controlled assistance level above, minimal skips all P-A*; quiet skips P-A* + P-I*; standard and full fire everything per the catalog.

Cost caps from ADR-0057 A-I3 apply on top — once a player hits their per-tier daily cap, narration falls back to manual templates rather than LLM-generated lines.

Source map

Concern Path (target)
ARIA personal intelligence service services/gameserver/src/services/aria_personal_intelligence_service.py
ARIA market intelligence service services/gameserver/src/services/aria_market_intelligence_service.py
Enhanced AI service (cross-cutting) services/gameserver/src/services/enhanced_ai_service.py
AI trading service (route opt) services/gameserver/src/services/ai_trading_service.py
ARIA models services/gameserver/src/models/aria_personal_intelligence.py
Player ARIA columns services/gameserver/src/models/player.py (aria_*)
Multilingual ARIA services/gameserver/src/services/multilingual_ai_service.py