# SPECIFICATIONS: ASTRAL AGENT ORB DELEGATION & MULTI-LLM AUTONOMOUS SYSTEM
# FREEEXILE PROJECT: DARK MARTIAL ASTRAL ARPG 2.5D

> **Responsible Roles**: Lead Systems Designer (`lead_systems_designer`), Lead Server Architect (`server_systems_architect`), Lead Documentation Architect (`lead_documentation_architect`), Chief Security Architect (`security_anticheat_lead`).  
> **Document Version**: 1.0.0-RELEASE  
> **Implementation Status**: Fully Implemented & Tested (118/118 Tests Passed - 100% Green Suite).  
> **Applies to**: Server-Authoritative Loop, WebApp Mobile Simulator, iOS Metal Engine, Multi-LLM API Gateway.

---

## 1. DESIGN PHILOSOPHY & LORE

In the Dark Martial cosmos of `FreeExile`, advanced cultivators can project an **Astral Avatar (Chiến Hồn Dã Tính)**. When players are busy at work, study, or offline sleeping, they activate an **Agent_Orb (Chiến Hồn Tế Cốt)** to entrust their character to an autonomous AI Agent.

```
                    ┌────────────────────────────────────────┐
                    │          BUSY / OFFLINE PLAYER         │
                    └───────────────────┬────────────────────┘
                                        │ Activates
                                        ▼
                          🔮 [ASTRAL AGENT ORB]
                                        │
              ┌─────────────────────────┴─────────────────────────┐
              ▼                                                   ▼
  ┌───────────────────────┐                           ┌───────────────────────┐
  │ LOW-LEVEL REFLEX CORE │                           │ HIGH-LEVEL LLM BRAIN  │
  │ (30Hz Tick < 33.3ms)  │                           │ (3 - 5 Second Cycle)  │
  ├───────────────────────┤                           ├───────────────────────┤
  │ • Evasion i-frame <25%│◄──── Tactical Guidance ───│ • DeepSeek V3 / R1    │
  │ • Ground Loot pickup  │     (Target Priority,     │ • OpenRouter Universal│
  │ • Five Elements skill │      Stance, Route Plan)  │ • OpenAI GPT-4o       │
  │ • Health elixir use   │                           │ • Anthropic Claude 3.5│
  └───────────┬───────────┘                           │ • Google Gemini 1.5   │
              │                                       │ • Moonshot AI Kimi    │
              ▼                                       └───────────────────────┘
  ┌───────────────────────────────────────────────────────────────────────────┐
  │              SERVER-AUTHORITATIVE ENGINE & MOVEMENT AUTHORITY             │
  │      (Zero-Trust Validation: Anti-cheat, Spatial bounds, Inventory locks) │
  └───────────────────────────────────────────────────────────────────────────┘
```

---

## 2. AGENT ORB TIERS & RECIPES

| Item ID | Name | Duration | Acquisition | Capabilities |
| :--- | :--- | :--- | :--- | :--- |
| `item_agent_orb_tier1` | **Astral Orb of Awakening (Tier 1)** | 2 Hours (7,200s) | Crafting (5x Crude Flint + 1x Primal Bloodstone) or MegaShop (200 Gold Cores) | Auto-patrol, mob hunting, Five Elements countering, nearby loot pickup. |
| `item_agent_orb_tier2` | **Astral Orb of the Sovereign (Tier 2)** | 8 Hours (28,800s) | Crafting (3x Chaos Stone + 1x Ancient Bone Brand) or MegaShop (600 Gold Cores) | Auto-elixir consumption when HP < 30%, Phantom Evasion 0.25s i-frame defense. |
| `item_agent_orb_tier3` | **Primordial Void Mirror Avatar (Tier 3)** | 24 Hours (86,400s) | Crafting (1x Void Mirror + 5x Ancient Bone Brand) or MegaShop (1,500 Gold Cores) | Auto-stashing valuable loot to Consignment Vault with 2PC distributed locking. |

---

## 3. MULTI-LLM INTEGRATION MATRIX

Implemented at [`server/agent/llm_provider_client.py`](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py):
1. **Local Tactical Reflex (`LOCAL_TACTICAL`)**: Deterministic 0ms heuristic engine running offline on server/client. Guarantees zero latency and emergency survivability.
2. **DeepSeek (`DEEPSEEK`)**: `deepseek-chat` / `deepseek-reasoner`. Low cost, deep chain-of-thought tactical evaluation.
3. **OpenRouter (`OPENROUTER`)**: Universal gateway supporting open-source and global models (`meta-llama/llama-3.3-70b-instruct`).
4. **OpenAI (`OPENAI`)**: `gpt-4o-mini` / `gpt-4o` with strict JSON mode schema compliance.
5. **Anthropic (`ANTHROPIC`)**: `claude-3-5-haiku` / `claude-3-5-sonnet` via Messages API.
6. **Google Gemini (`GEMINI`)**: `gemini-1.5-flash` / `gemini-2.0` via Google GenAI REST.
7. **Moonshot AI Kimi (`KIMI`)**: `moonshot-v1-8k` long context buffer for multi-hour battle memory.

---

## 4. TACTICAL STANCES

- **Aggressive (⚔️ Cương Mãnh)**: Engages all enemies within 15m radius, maximizes EXP/hour, only dodges below 15% HP.
- **Balanced (⚖️ Cân Bằng)**: Recommended default. Balanced farming, Five Elements counter combos, dodges below 25% HP.
- **Treasure Hunter (💎 Tầm Bảo)**: Prioritizes Primal Bloodstones and Ancient Bone Brands above combat.
- **Defensive (🛡️ Ẩn Nhẫn)**: Retreats and heals whenever HP drops below 50%, pulls isolated monsters.

---

## 5. TDD VERIFICATION SUMMARY

All subsystems have been rigorously verified:
- `test_llm_provider_client.py`: 5 passed
- `test_agent_decision_core.py`: 5 passed
- `test_agent_orb_service.py`: 6 passed
- `test_mobile_webapp_config.py`: 6 passed
- Workspace Total: **118 passed in 0.80s**.