Eu4kdb20

EU4-KB is an offline-first knowledge and diagnostic engine for Europa Universalis IV modding. It gives coding agents and mod tools deterministic access to documented effects, triggers, scopes, modifiers, mechanics, examples, symbols, localisation, and cross-file findings without repeatedly searching the web.

The original Wiki corpus and mission-tree intelligence remain intact. Version 2.1 adds a pinned live-Wiki delta audit, semantic CWTools ingestion, evidence/confidence classes, cross-file guidance, real-project pattern summaries, and source/coverage audit commands. Basic use requires only Python 3.10+ and the standard library.

Status: 2.1 alpha, external-knowledge foundation. The tools deliberately report unknown or dependency-sensitive facts as UNCERTAIN; they do not pretend to implement every engine rule. The documentation snapshot includes records with version notes through EU4 1.37, but the corpus does not establish one single target patch.

Quickstart

python -m pip install -e .
eu4kb build
eu4kb verify
eu4kb search "government reform gui"
eu4kb get effect add_stability --json
eu4kb scope every_owned_province
eu4kb get custom_button
eu4kb sources
eu4kb wiki-diff
eu4kb external-coverage

No install is required from the repository: replace eu4kb with python -m eu4kb.

Agent-sized retrieval

eu4kb search "mission tooltip hidden effect" --context short --max-results 5 --json
eu4kb get trigger has_reform --context normal --json
eu4kb related imperial_authority --json
eu4kb --eu4-version 1.35 get effect add_stability --json

Search weights exact names, aliases, kinds, categories, descriptions, examples, headings, and source metadata. Agent JSON defaults to five short results, deduplicates citations, and always remains valid when --max-chars truncates the ranked result set. short is for discovery, normal includes implementation detail while summarizing unusually large nested schemas, and full is lossless. Exact get --context full remains available when the complete record is genuinely needed.

Index a mod or local game installation

eu4kb index-mod C:\mods\my_mod
eu4kb find-symbol my_scripted_effect --index C:\mods\my_mod\.eu4kb\index.json
eu4kb examples add_stability --index C:\mods\my_mod\.eu4kb\index.json

eu4kb index-vanilla "C:\Program Files (x86)\Steam\steamapps\common\Europa Universalis IV" --register "EU4 Vanilla"
eu4kb examples government_reform --reference "EU4 Vanilla"
eu4kb references

Vanilla files are never copied into this repository. The local index contains relative paths, symbols, bounded snippets, scope context, version/build metadata when present, and a source fingerprint. Vanilla indexes default to the user's local application-data cache; mod indexes default to <mod>/.eu4kb/index.json. --register adds a friendly name to the user-local reference registry so agents do not need to repeat index paths.

Validate and diagnose

eu4kb validate C:\mods\my_mod\missions\example.txt
eu4kb localization-check C:\mods\my_mod --json
eu4kb explain-scope C:\mods\my_mod\missions\example.txt:120 --json
eu4kb diagnose-mod C:\mods\my_mod --markdown
eu4kb diagnose-mod C:\mods\my_mod --json --severity warning
eu4kb analyze-missions C:\mods\my_mod --mission my_capstone --json

Implemented checks include malformed tokens, quotes and braces; duplicate symbols/event IDs; undeclared event namespaces; unresolved local scripted calls; localisation encoding, headers, entries and duplicates; documented mission/decision/reform/religion localisation; mission topology; event text keys; documented effect/trigger/scope incompatibilities; and conservative CWTools-backed direct-field cardinality/primitive checks in matching content roots.

Mission-tree analysis additionally emits a machine-readable designed graph with slots, positions, prerequisites, children, depth, root-derived branches, convergence/divergence, components, and visual neighbors. It reviews direct-model connector crossings, dimensions, whitespace, isolated components, redundant edges, excessive linearity, branch imbalance, weak convergence, and repeated requirements/rewards. See Mission tree design intelligence and AI usage.

Severity is intentional:

• ERROR: contradicted by parsed project state or documented scope/syntax rules.
• WARNING: likely problem, but vanilla/load-order context may resolve it.
• UNCERTAIN: not defined locally or documented as built-in; may come from a dependency.
• INFO: useful non-failing observation.

Python API

from eu4kb import KnowledgeBase

kb = KnowledgeBase.open()
results = kb.search("government reform", limit=5)
effect = kb.get("effect", "add_stability")
scope = kb.get("scope", "every_owned_province")

The CLI, generated indexes, diagnostics, and MCP adapter reuse the same library.

Optional MCP server

python -m pip install -e ".[mcp]"
eu4kb-mcp

This starts a stdio MCP server exposing search, exact retrieval, related mechanics, script validation, mod diagnostics, local symbol lookup, examples, and scope explanation. Retrieval tools default to bounded short/normal payloads and accept context plus max_chars when more detail is necessary. It targets the current official MCP Python SDK v2 API; MCP is not required for normal use.

Repository layout

• kb/ — committed human-readable Wiki-derived articles and province map.
• data/ — structured Wiki and external schemas, roots, enums, scopes, localisation, patterns, sources, and troubleshooting records.
• external/ — normalized source snapshots, revision metadata, and pattern summaries; never source trees.
• index/ — deterministic entity, alias, relationship, search, and article manifests.
• eu4kb/ — importable standard-library core.
• tools/ — backward-compatible HTML converter, manifest generator, publisher, and original tests.
• tests/ — parser, extraction, indexing, diagnostics, determinism, and CLI regression tests.
• docs/ — architecture, schemas, and AI workflows.

See Architecture, Schemas, local reference corpora, and AI usage.

Build and compatibility

eu4kb build regenerates structured catalogs and indexes from committed kb/; eu4kb verify confirms they are current. Output is sorted, timestamp-free, newline-stable, and reproducible.

The original commands remain:

python tools/build_kb.py
python tools/gen_manifest.py
python -m unittest discover -s tools -p "test_*.py"

The public checkout intentionally omits raw/ saved HTML for licensing/distribution reasons. Legacy converter commands now fail safely without modifying kb/ when those inputs are absent. When private raw inputs are available, conversion is staged and only replaces kb/ after every page passes quality control.

Testing

python -m unittest discover -s tools -p "test_*.py"
python -m unittest discover -s tests -p "test_*.py"
python -m eu4kb verify

Attribution and licensing

Reference content under kb/ is derived from the Europa Universalis IV Wiki under CC BY-SA 3.0 and remains under that licence and its authors' copyright. The MIT licence covers project tooling. Do not commit vanilla EU4 game files or generated local vanilla indexes.

The optional server follows the official MCP Python SDK, whose v2 line uses MCPServer and supports stdio.