pf1e-simulator/docs/architecture/technical-architecture.md

Architecture technique

Modules principaux

Module	Responsabilité
combat.py	CombatEngine : initiative, actions, résolution attaques, états de vie, incantation, invocation, manœuvres, transcript, politique par défaut, Observation/LLMPolicy
dice.py	Parseur notation dés (2d4+1) + lancer
rng.py	SeededRng (flux reproductible par graine), ScriptedRng (tests)
models.py	Schémas Pydantic v2 : Combatant, AbilityScores, ACProfile, AttackSpec, DamageComponent, Saves, DamageReduction
map.py	MapSpec/TerrainType, chargement YAML, validation (dimensions, chars, zones, déploiement, markers)
grid.py	Grille 5-10-5 : distance, step_cost, diagonal_allowed, Dijkstra reachable, airborne_view
los.py	Ligne d'effet, couvert par règle des coins : gate dans weapon_for, bonus dans resolve_attack
areas.py	Géométrie gabarits zone : cone_cells (quart cercle 90°), line_cells (Bresenham 5ft), bursts via _area_creatures
combat.py	CombatEngine déterministe : initiative, actions, résolution attaques, tailles/allonges, high ground, actions immédiates opt-in, états de vie, incantation, invocation, manœuvres, capacités de classe, transcripts, politique par défaut, Observation/LLMPolicy
effects.py	StatModifier + resolve_modifiers (empilement PF1e : dodge/racial/trait/sans-type s'additionnent ; moral/sacré/profane/enhancement gardent le max)
conditions.py	29 conditions PF1e : Condition (modificateurs + flags comportementaux + miss_chance)
abilities.py	Dons : AbilitySpec + fabriques (Weapon Focus, Toughness, Power Attack actif −X/+2X, X=BAB//4+1)
spells.py	SpellSpec (niveau, école, portée, save, DC, requires_ranged_touch, harmless, cast_time, components) + effets (DamageEffect, ConditionEffect, HealEffect, BuffEffect, AreaEffect, OneShotEffect) + scalage (scaling dés, scaling_flat bonus plat)
metrics.py	win_rate, win_rate_sigma, win_rate_band (bande 3σ bornée [0,1])
runner.py	EncounterSpec/Side, build_states (placement + désambiguïsation ids), run_encounter (1 SeededRng/run), EncounterReport + attrition
objectives.py	Primitives Phase 2 : P(survie), P(TPK), P(≥1 mort), PV perdus, rounds, dcile PV restants
phase2_spike.py	Politique "focus fire" + cartographie danger
cli.py	argparse pf1e-sim, rapport FR, codes sortie, flags --llm-report/--output
loaders/combatant.py	Chargeur unifié PJ + monstres : résolution dons → AbilitySpec, sorts → Combatant.spells
loaders/foundry.py	Migration Foundry one-shot (incomplet — ne pas régénérer data/pcs/*.json)
report.py	LLM report writer P5.3 : ReportContext, LLMReportPolicy, ReportBudget, format_llm_report

Flux de données principal

CLI (args) → _build_spec() → EncounterSpec
    ↓
load_spell_registry() → spell_registry
    ↓
run_encounter(spec, runs, seed, spell_registry, ...)
    ↓
Pour chaque run: SeededRng(seed+i) → CombatEngine → CombatResult
    ↓
Agrégation → EncounterReport (wins, draws, avg_rounds, attrition)
    ↓
format_report() → sortie FR

Frontière LLM (Phase 2/3)

CombatEngine(llm_policy=LLMPolicy) → avant chaque appel politique:
    Observation snapshot (to_dict() → JSON isolé)
    LLMPolicy(observation) → tuple[Action, ...]

• LLM ne reçoit que le snapshot, jamais engine.*
• PromptPack externe (PF1E_PROMPT_PACK_DIR) : version.txt + <name>.md + <name>.examples.json
• prompt_version = version:name:hash12 (clé cache composite D6)
• Cache ResponseCache (clé = modèle|params|prompt_version|schema|prompt_hash)
• Budget CostBudget + CircuitBreaker + retry/backoff

Tests & qualité

• Transcripts épinglés (combats 1v1/2v2 scriptés via ScriptedRng)
• Assertions statistiques forme fermée (matchup symétrique dans bande 3σ)
• Gate : uv run pytest -q && uv run ruff check src tests && uv run basedpyright src
• Ruff select = ["ALL"], ligne 100 ; basedpyright strict sur src + tests