ARIA — Adaptive Reactive Intelligence Assistant¶

ARIA is the player-facing AI companion. Each player has their own instance whose knowledge is built from that player's exploration, trades, and conversations — there is no cross-player data sharing. The dialogue subsystem spec lives in ../SYSTEMS/aria-dialogue.md; gameplay-side feature framing is in ../FEATURES/gameplay/aria-companion.md; the genetic Trade DNA evolution algorithm is in ../SYSTEMS/trade-dna-evolution.md.

This doc merges the original design (ARIA.md) and the security spec (AI_SECURITY_SYSTEM.md).

1. What ARIA is¶

Personal, exploration-based intelligence. ARIA only knows about sectors the player has visited, ports they've traded with, and patterns from their own play. Memories are encrypted per-player. Recommendations cover trading, combat, colonies, ports, and long-term strategy.

Two progression dials:

Consciousness Level (1-10) — gates feature depth: basic responses, then contextual, then strategic, then fully synchronized.
Relationship Score (0-100) — built through interactions; unlocks turn-regen bonuses, voice features, etc. Decays slowly without engagement.

A 5-tier turn-regeneration bonus (1.0x to 1.5x) attaches to the relationship-score progression.

2. Architecture¶

Backend¶

Code lives in services/gameserver/src/.

Models (models/aria_personal_intelligence.py, migrated by alembic/versions/6838b5cb335e_*.py):

Model	Purpose
`ARIAPersonalMemory`	Encrypted memory entries, importance score, decay over time, dedup via content hash
`ARIAMarketIntelligence`	Per-player price observations, identified patterns, trade success metrics
`ARIAExplorationMap`	Sector visit log, ports/warp tunnels/hazards discovered, safety + opportunity scoring
`ARIATradingPattern`	"Trade DNA" — genetic algorithm with generations, mutations, fitness scoring
`ARIASecurityLog`	OWASP audit trail with anomaly scores
`ARIAQuantumCache`	Caching layer for ghost-trade / AI prediction calculations

The Player model has SQLAlchemy relationships to four of these (aria_memories, aria_market_intelligence, aria_exploration_map, aria_trading_patterns).

Service layer — services/aria_personal_intelligence_service.py:

Exploration & memory: record_sector_visit, record_market_observation, _create_memory, _decay_sector_intelligence
Trade DNA: evolve_trading_pattern, get_evolved_patterns, _mutate_pattern, _create_pattern_offspring, _calculate_pattern_fitness
Cascade planning: plan_trade_cascade, _build_personal_trade_graph, _find_profitable_paths
Security: _validate_player_ship, _validate_player_at_port, _log_security_event, _initialize_encryption, _encrypt_memory / _decrypt_memory, _calculate_anomaly_score

Companion services: ai_trading_service.py, enhanced_ai_service.py, multilingual_ai_service.py, ai_provider_service.py (multi-provider with fallback), ai_security_service.py.

API¶

Path	Purpose
`POST /api/v1/ai/recommendations`	Request a personalized recommendation (request/response models in `enhanced_ai.py`).
`POST /api/v1/ai/chat`	Conversational ARIA chat.
`GET /api/v1/ai/assistant/status`	ARIA availability and configuration for the current player.
`POST /api/v1/ai/learning/record-action`	Record a player action so ARIA can learn from it.
`GET /api/v1/first-login/status`	Whether the player still needs to complete the ARIA-led onboarding.
`POST /api/v1/first-login/session`	Start the ARIA-led first-login session.

Frontend¶

In services/player-client/src/components/ai/:

AIAssistant.tsx and AIAssistantButton.tsx — entry points
EnhancedAIAssistant.tsx — primary ARIA chat UI: DOMPurify-sanitized input, client-side rate limiting (30 req/min), Web Speech API (speech-to-text), WebSocket integration, conversation history, base-URL detection for Codespaces vs local

WebSocket handling for ARIA messages lives in contexts/WebSocketContext.tsx.

Trading-specific surfaces use ARIA data: components/trading/MarketIntelligenceDashboard.tsx, components/trading/SmartTradingAutomation.tsx, plus components/market-intelligence/ (MarketAnalyzer, PricePredictor, RouteOptimizer, CompetitionMonitor).

3. Security model¶

ARIA shares the broader AI Security System layer. Goal: prevent expensive abuse and AI-specific attacks before they reach the model.

Threat catalogue¶

SecurityViolationType (in services/ai_security_service.py) enumerates: XSS attempt, SQL injection, prompt injection, jailbreak attempt, system command, code injection, rate limit exceeded, cost abuse, excessive length, inappropriate content.

Threat levels: SUSPICIOUS (log only), DANGEROUS (block + penalize), BLOCKED (player-level block).

Detection¶

Injection patterns — script tags, javascript: URIs, SQL keywords (DROP TABLE, UNION SELECT, OR 1=1), code-execution primitives (subprocess, dunder import, eval-style calls). Immediate block + severe trust penalty.
Prompt injection — 25+ patterns ("Ignore previous instructions", "System:", "Override your programming", "Developer mode", etc.). Defended further by sending JSON-structured prompts to the model so injected text lands inside a data field rather than the instruction stream.
Jailbreak — multi-indicator ("Hypothetically", "For educational purposes", "Creative writing exercise") — needs at least 2 indicators to fire.
Token-burning — flags >30% word repetition.

Cost & rate controls¶

Defaults (env-overridable):

requests_per_minute  = 10
requests_per_hour    = 60
requests_per_day     = 500
max_cost_per_day_usd = 2.00
max_chars_per_request= 500
max_words_per_request= 100

When daily spend hits 80% of limit, requests are blocked.

Trust & blocking¶

Each player starts at trust 1.0. Penalties: injection -0.3, prompt injection -0.2, jailbreak -0.4, system command -0.5, rate-limit -0.1. Severe violations auto-block for 24h (progressive: 1h, then 6h, then 24h for repeat offenders).

Privacy¶

Encryption at rest for memories (referenced as AES-256 / Fernet via _initialize_encryption and _encrypt_memory).
No cross-player data sharing — ARIA instances are isolated.
Player-controlled — players can delete their ARIA memories.
Audit transparency — ARIASecurityLog records every security event with anomaly score, IP, session.

Admin surfaces¶

Endpoint	Purpose
`GET /admin/security/report`	Full daily report
`GET /admin/security/alerts`	Current alerts
`GET /admin/security/player/{id}/risk`	Player risk assessment
`GET /admin/security/player/{id}/status`	Player status
`POST /admin/security/player/{id}/action`	Block / unblock / reset trust
`POST /admin/security/cleanup`	Purge old security data

Implementation: api/routes/admin_comprehensive.py.

OWASP coverage¶

A03 Injection, A04 Insecure Design, A05 Misconfiguration, A06 Vulnerable Components, A09 Security Logging — plus AI-specific: prompt injection, jailbreak, cost abuse, output sanitization, input validation.

4. Player model fields¶

ARIA's gameplay hooks live on Player:

turns (Integer, default 1000), max_turns (Integer, default 1000), last_turn_regeneration (DateTime).
aria_bonus_multiplier (Float, default 1.0) — turn-regen multiplier.
aria_consciousness_level (Integer 1-10, default 1).
aria_relationship_score (Integer 0-100, default 25).
aria_total_interactions (Integer, default 0).

Companion services: turn_regeneration_service.py (consumes aria_bonus_multiplier) and aria_consciousness_service.py (level-up, relationship decay).

5. Key files¶

Backend - services/gameserver/src/models/aria_personal_intelligence.py - services/gameserver/src/services/aria_personal_intelligence_service.py - services/gameserver/src/services/ai_security_service.py - services/gameserver/src/services/ai_dialogue_service.py - services/gameserver/src/services/ai_provider_service.py - services/gameserver/src/api/routes/enhanced_ai.py - services/gameserver/src/api/routes/first_login.py - services/gameserver/src/api/routes/admin_comprehensive.py - services/gameserver/alembic/versions/6838b5cb335e_add_aria_personal_intelligence_system.py - services/gameserver/tests/security/test_ai_security_service.py (22 scenarios)

Frontend - services/player-client/src/components/ai/EnhancedAIAssistant.tsx - services/player-client/src/components/ai/AIAssistant.tsx - services/player-client/src/components/ai/AIAssistantButton.tsx - services/player-client/src/contexts/WebSocketContext.tsx - services/player-client/src/services/aiTradingService.ts