diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c0fccd5
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,22 @@
+/reference
+
+# Python
+__pycache__/
+.pytest_cache/
+.venv/
+*.pyc
+
+# Agent runtime
+koboldcpp.exe
+model.gguf
+*.gguf
+data/
+src/LocalDiplomacy.Agent/data/
+src/LocalDiplomacy.Agent/koboldcpp.exe
+src/LocalDiplomacy.Agent/model.gguf
+src/LocalDiplomacy.Agent/config.yaml
+
+# .NET/Bannerlord build output
+bin/
+obj/
+*.user
diff --git a/LocalDiplomacy.sln b/LocalDiplomacy.sln
new file mode 100644
index 0000000..3365e6e
--- /dev/null
+++ b/LocalDiplomacy.sln
@@ -0,0 +1,29 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.5.2.0
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "LocalDiplomacy", "src\LocalDiplomacy\LocalDiplomacy.csproj", "{5FF51413-8983-57DD-BFCC-236F7B3B3F5F}"
+EndProject
+Global
+ GlobalSection(SolutionConfigurationPlatforms) = preSolution
+ Debug|Any CPU = Debug|Any CPU
+ Release|Any CPU = Release|Any CPU
+ EndGlobalSection
+ GlobalSection(ProjectConfigurationPlatforms) = postSolution
+ {5FF51413-8983-57DD-BFCC-236F7B3B3F5F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {5FF51413-8983-57DD-BFCC-236F7B3B3F5F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {5FF51413-8983-57DD-BFCC-236F7B3B3F5F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {5FF51413-8983-57DD-BFCC-236F7B3B3F5F}.Release|Any CPU.Build.0 = Release|Any CPU
+ EndGlobalSection
+ GlobalSection(SolutionProperties) = preSolution
+ HideSolutionNode = FALSE
+ EndGlobalSection
+ GlobalSection(NestedProjects) = preSolution
+ {5FF51413-8983-57DD-BFCC-236F7B3B3F5F} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+ EndGlobalSection
+ GlobalSection(ExtensibilityGlobals) = postSolution
+ SolutionGuid = {28D30FCB-3EC1-4E01-9CFE-F2BFF6280675}
+ EndGlobalSection
+EndGlobal
diff --git a/NuGet.config b/NuGet.config
new file mode 100644
index 0000000..765346e
--- /dev/null
+++ b/NuGet.config
@@ -0,0 +1,7 @@
+
+
+
+
+
+
+
diff --git a/docs/LocalDiplomacy_IMPLEMENTATION_STATUS.md b/docs/LocalDiplomacy_IMPLEMENTATION_STATUS.md
new file mode 100644
index 0000000..83fb12f
--- /dev/null
+++ b/docs/LocalDiplomacy_IMPLEMENTATION_STATUS.md
@@ -0,0 +1,153 @@
+# LocalDiplomacy Implementation Status
+
+Last updated: 2026-04-30
+
+## Working / Implemented
+
+### Bannerlord Module
+
+- Module folder exists at `module/LocalDiplomacy`.
+- `SubModule.xml` is present and configured for singleplayer.
+- Module builds to:
+ - `module/LocalDiplomacy/bin/Win64_Shipping_Client/LocalDiplomacy.dll`
+- Current dependencies:
+ - `Native`
+ - `SandBoxCore`
+ - `Sandbox`
+ - `StoryMode`
+- `LocalDiplomacy.SubModule` loads in Bannerlord.
+- Campaign behavior is registered on campaign game start.
+- Dedicated game-side log exists:
+ - `Documents/Mount and Blade II Bannerlord/Configs/ModLogs/LocalDiplomacy.log`
+- Dialogue hook is registered for several conversation tokens:
+ - `lord_pretalk`
+ - `lord_talk`
+ - `lord_talk_speak_diplomacy_2`
+ - `hero_main_options`
+ - `hero_talk`
+ - `start`
+- In-game dialogue option exists:
+ - `[LocalDiplomacy] Ask what news they have.`
+- Selecting the dialogue option sends a compact `ConversationRequest` to the local Python agent.
+- Game client is hardcoded to call:
+ - `http://127.0.0.1:8766`
+- Game client logs outgoing payloads and failed HTTP responses.
+- Agent responses are displayed in-game with `InformationManager.DisplayMessage`.
+- Returned game actions are passed through local validation before execution.
+- Action executor currently displays accepted actions as messages.
+
+### Python Agent
+
+- FastAPI agent exists at `src/LocalDiplomacy.Agent`.
+- Agent runs with `uv`.
+- Main app module:
+ - `localdiplomacy_agent.app:app`
+- Main endpoints implemented:
+ - `GET /health`
+ - `GET /debug/status`
+ - `POST /conversation/respond`
+ - `POST /world/tick`
+ - `POST /actions/result`
+- Web dashboard exists:
+ - `http://127.0.0.1:8766/ui`
+- Dashboard shows:
+ - agent status
+ - KoboldCpp reachability
+ - memory status
+ - last latency
+ - live logs
+ - KoboldCpp API address
+ - model id
+ - timeout
+- Dashboard can update KoboldCpp API settings.
+- Dashboard can ping KoboldCpp.
+- KoboldCpp API can point at another machine, for example:
+ - `http://192.168.1.17:5001`
+- Agent logs game requests, agent replies, queued actions, warnings, and errors.
+- Agent config persists to `config.yaml`.
+- Agent supports `/no_think` prompt prefixing for Qwen3-style thinking models.
+- Agent uses focused tool selection for action-looking requests.
+- Agent uses narrowed action schemas for small models.
+- Agent can force `propose_game_action` tool calls for explicit action requests.
+- Python contract accepts C#-style nullable `traits`.
+- Memory layer scaffold exists and currently defaults to disabled.
+- SQLite event ledger exists.
+
+### KoboldCpp / Model Testing
+
+- KoboldCpp OpenAI-compatible `/v1/chat/completions` flow is implemented.
+- Tool calling uses OpenAI-style `tools` and `tool_choice`.
+- Model smoke-test script exists:
+ - `scripts/test_kobold_model.py`
+- Smoke-test script accepts:
+ - model path
+ - context size
+ - KoboldCpp path
+ - port
+ - keep-running flag
+ - stop-existing flag
+ - extra KoboldCpp args
+- Smoke-test script runs:
+ - normal dialogue test
+ - auto tool-call test
+ - forced tool-call test
+ - LocalDiplomacy action-planner tool-call test
+- `Qwen3-4B-abliterated-q4_k_m.gguf` was tested at `40960` context and passed smoke tests with `/no_think`.
+
+### Tests / Build
+
+- Python test suite passes.
+- Current Python test count:
+ - 11 tests
+- C# module builds successfully with local .NET SDK and Bannerlord references.
+- Build command:
+ ```powershell
+ $env:PATH="$env:USERPROFILE\.dotnet;$env:PATH"
+ $env:BANNERLORD_REFERENCES="D:\SteamLibrary\steamapps\common\Mount & Blade II Bannerlord\bin\Win64_Shipping_Client"
+ dotnet build src\LocalDiplomacy\LocalDiplomacy.csproj
+ ```
+
+## Partially Implemented / Scaffolded
+
+### Bannerlord Gameplay Integration
+
+- Dialogue integration is currently a single debug-style option.
+- Player cannot yet type custom dialogue text inside Bannerlord.
+- NPC answer is currently displayed as an information message, not as a full custom conversation UI.
+- No Gauntlet UI has been built inside the game.
+- No confirmation UI exists yet for dangerous actions.
+- Local validation exists, but most action-specific validation is still basic.
+- Action execution is mostly placeholder behavior.
+- World tick endpoint exists, but the game does not yet send rich world diffs.
+- Nearby parties, settlements, kingdom state, and recent events are still minimal in the in-game request.
+
+### Agent
+
+- Tool registry contains broad AIInfluence-style feature coverage.
+- Many tools are declared but backed by placeholder/read-only behavior until the Bannerlord connector supplies richer live data.
+- Memory storage is scaffolded but disabled by default.
+- Mem0 + Qdrant is planned but not wired as the default runtime path yet.
+- No separate desktop UI exists; the current UI is browser-based FastAPI HTML.
+
+## Known Issues / Watch Items
+
+- Small models can narrate tool intentions unless `/no_think`, narrowed schemas, and forced tool calls are used.
+- Full tool catalog is too large for reliable 4B model tool choice.
+- The Python dashboard updates KoboldCpp settings at runtime, but active in-flight calls use the currently loaded config object.
+- Bannerlord must be closed before rebuilding if the DLL is locked.
+- The first working in-game path depends on the player selecting the debug dialogue option.
+- Returned action execution is intentionally conservative and mostly non-mutating.
+
+## Next Recommended Work
+
+1. Replace the debug prompt with a small in-game text input or selectable prompt menu.
+2. Show NPC responses in a proper dialogue/inquiry window instead of only notification messages.
+3. Expand `BuildDebugConversationRequest` with real nearby parties, settlement, war, clan, and kingdom context.
+4. Add confirmation UI for diplomacy, hostile, and high-impact actions.
+5. Implement a small set of real Bannerlord mutations:
+ - follow player
+ - patrol settlement
+ - propose peace
+ - declare war proposal validation only
+6. Wire world tick diffs from Bannerlord to the agent.
+7. Enable Mem0 + Qdrant memory once the dialogue loop is stable.
diff --git a/docs/LocalDiplomacy_PLAN.md b/docs/LocalDiplomacy_PLAN.md
new file mode 100644
index 0000000..4b52ee0
--- /dev/null
+++ b/docs/LocalDiplomacy_PLAN.md
@@ -0,0 +1,759 @@
+# LocalDiplomacy Architecture Plan
+
+## Summary
+
+LocalDiplomacy is a Mount & Blade II: Bannerlord singleplayer mod that keeps the roleplay and diplomacy feel of AIInfluence while moving AI orchestration out of the game process.
+
+The game mod should be a thin, safe client. It captures compact world and dialogue context from Bannerlord, displays AI-driven conversations and events, validates proposed actions, and executes only whitelisted mutations. The external `LocalDiplomacy.Agent` service owns prompt construction, memory retrieval, KoboldCpp calls, tool execution, and audit logging.
+
+Default stack:
+
+- Bannerlord C# module: `LocalDiplomacy`
+- External service: Python 3.11+ FastAPI app, `LocalDiplomacy.Agent`
+- LLM backend: KoboldCpp OpenAI-compatible `/v1/chat/completions`, launched by the agent from the app working directory
+- Local memory: Mem0 OSS with Qdrant
+- Audit/source-of-truth event log: SQLite
+- Tool calling: OpenAI-style tools, with mod-side validation before any Bannerlord mutation
+
+## Goals
+
+- Replace giant prompt text files with compact, structured game-state packets.
+- Keep rich NPC dialogue, world events, and diplomatic statements.
+- Allow AI to propose actions, but never let AI directly mutate the game.
+- Make the AI layer swappable and debuggable outside Bannerlord.
+- Store long-term character, kingdom, and campaign memories locally.
+- Keep all player and campaign data on the user's machine by default.
+
+## Non-Goals For v1
+
+- Do not copy AIInfluence source, binary code, or assets.
+- Do not implement intimate/child systems in the first pass.
+- Do not implement TTS, STT, lip-sync, or generated voice in the first pass.
+- Do not require cloud APIs.
+- Do not send full save files, huge world dumps, or unbounded conversation logs to the model.
+
+## Repository Layout
+
+Target layout:
+
+```text
+LocalDiplomacy/
+├── docs/
+│ └── LocalDiplomacy_PLAN.md
+├── src/
+│ ├── LocalDiplomacy/
+│ │ ├── LocalDiplomacy.csproj
+│ │ ├── SubModule.cs
+│ │ ├── Agent/
+│ │ ├── Campaign/
+│ │ ├── Contracts/
+│ │ ├── Diplomacy/
+│ │ ├── Settings/
+│ │ └── UI/
+│ └── LocalDiplomacy.Agent/
+│ ├── pyproject.toml
+│ ├── config.example.yaml
+│ ├── localdiplomacy_agent/
+│ │ ├── app.py
+│ │ ├── config.py
+│ │ ├── contracts.py
+│ │ ├── koboldcpp_client.py
+│ │ ├── memory.py
+│ │ ├── prompts.py
+│ │ ├── tools.py
+│ │ └── event_log.py
+│ └── tests/
+└── module/
+ └── LocalDiplomacy/
+ ├── SubModule.xml
+ ├── bin/
+ ├── GUI/
+ └── ModuleData/
+```
+
+## Bannerlord Module Design
+
+The Bannerlord module should stay intentionally small and defensive.
+
+Responsibilities:
+
+- Load as a singleplayer module named `LocalDiplomacy`.
+- Register campaign behavior for dialogue and world tick hooks.
+- Collect relevant context from Bannerlord APIs.
+- Serialize context into compact JSON requests.
+- Send requests to the local agent.
+- Render NPC replies, world events, and diplomatic statements.
+- Validate proposed actions against current game state.
+- Execute approved and valid actions.
+- Report action results back to the agent.
+
+Suggested dependencies:
+
+- `Bannerlord.Harmony`
+- `Bannerlord.UIExtenderEx`
+- Native Bannerlord modules: `Native`, `SandBoxCore`, `Sandbox`, `StoryMode`, `CustomBattle`
+- Optional later: MCM for settings UI
+
+Core C# subsystems:
+
+- `AgentClient`: HTTP client for the FastAPI service.
+- `ContextBuilder`: creates compact request DTOs from Bannerlord state.
+- `ActionValidator`: checks proposed actions against whitelists and live state.
+- `ActionExecutor`: mutates Bannerlord only after validation.
+- `DialogueBehavior`: hooks conversation entry points.
+- `WorldTickBehavior`: sends periodic compact world diffs.
+- `LocalDiplomacySettings`: service URL, timeout, debug flags, confirmation policy.
+- `DebugLog`: mod-local logs for requests, responses, validation failures, and connectivity.
+
+Feature coverage from `reference/aiinfulence_features.md` must be represented in the Bannerlord connector as validated action/context categories, not as in-game AI logic. The connector should expose live state and validate proposals for AI dialogue, NPC memory, trust/lie reactions, dynamic world events, diplomacy, romance/intimacy, settlement combat, death history, party tasks, trade/workshops/items, naval context, recruitment opportunities, visit history, non-combatant protection, and economic effects.
+
+## External Agent Design
+
+`LocalDiplomacy.Agent` is a local FastAPI app listening on `127.0.0.1:8766`.
+
+Responsibilities:
+
+- Accept compact game-state requests from the mod.
+- Locate and launch `koboldcpp.exe` and `model.gguf` from the directory the app is run from.
+- Monitor the KoboldCpp child process and wait for its API to become reachable before accepting AI requests.
+- Retrieve relevant memories from Mem0/Qdrant.
+- Read recent events from SQLite.
+- Build bounded prompts/messages.
+- Call KoboldCpp via OpenAI-compatible chat completions.
+- Provide tool schemas to KoboldCpp.
+- Execute local read/write-intention tools.
+- Return final assistant text and action proposals to the mod.
+- Persist memory writes and audit events.
+
+Default command:
+
+```powershell
+uvicorn localdiplomacy_agent.app:app --host 127.0.0.1 --port 8766
+```
+
+Expected runtime files in the app working directory:
+
+```text
+LocalDiplomacy.Agent/
+├── koboldcpp.exe
+├── model.gguf
+├── config.yaml
+└── data/
+```
+
+On startup, the agent should:
+
+1. Resolve the current working directory.
+2. Verify `koboldcpp.exe` exists there.
+3. Verify `model.gguf` exists there.
+4. Start KoboldCpp as a child process if no compatible server is already reachable at the configured URL.
+5. Launch with the configured port, context size, GPU flags, and `--jinjatools`.
+6. Poll `/api/extra/version` or `/v1/models` until ready.
+7. Surface a clear `/health` error if the executable, model, or API startup fails.
+
+Default config:
+
+```yaml
+server:
+ host: "127.0.0.1"
+ port: 8766
+
+koboldcpp:
+ autostart: true
+ executable_path: "./koboldcpp.exe"
+ model_path: "./model.gguf"
+ base_url: "http://127.0.0.1:5001"
+ chat_path: "/v1/chat/completions"
+ model: "local-model"
+ port: 5001
+ context_size: 8192
+ extra_args:
+ - "--jinjatools"
+ timeout_seconds: 120
+ tool_mode: "openai_tools"
+ json_repair_retry: true
+
+memory:
+ provider: "mem0"
+ vector_store: "qdrant"
+ qdrant_host: "127.0.0.1"
+ qdrant_port: 6333
+ collection: "localdiplomacy_memories"
+ embedder_provider: "ollama"
+ embedder_model: "nomic-embed-text"
+ llm_provider: "openai_compatible"
+
+event_log:
+ sqlite_path: "./data/localdiplomacy_events.sqlite3"
+
+generation:
+ temperature: 0.7
+ max_tokens: 800
+```
+
+## KoboldCpp Integration
+
+Use KoboldCpp latest stable. For packaged/local use, place `koboldcpp.exe` and the selected GGUF model named exactly `model.gguf` in the directory where `LocalDiplomacy.Agent` is run. The agent should launch KoboldCpp automatically using those files.
+
+Default agent-launched command:
+
+```powershell
+.\koboldcpp.exe --model .\model.gguf --port 5001 --contextsize 8192 --jinjatools
+```
+
+Manual launch remains useful for debugging:
+
+```powershell
+koboldcpp.exe --model C:\Models\your-model.gguf --port 5001 --contextsize 8192 --jinjatools
+```
+
+Use `--jinja` or a custom chat template only when `model.gguf` requires it. Some modern instruct models are template-sensitive, so every model should pass a smoke test before gameplay.
+
+Agent request shape:
+
+```json
+{
+ "model": "local-model",
+ "messages": [
+ { "role": "system", "content": "LocalDiplomacy system instructions..." },
+ { "role": "user", "content": "Compact scene packet..." }
+ ],
+ "tools": [],
+ "tool_choice": "auto",
+ "temperature": 0.7,
+ "max_tokens": 800
+}
+```
+
+Tool loop:
+
+1. Agent sends messages plus tool schemas to KoboldCpp.
+2. If the assistant returns `tool_calls`, the agent executes those tool handlers locally.
+3. Agent appends `role: tool` messages with results.
+4. Agent calls KoboldCpp again until the assistant returns final text or a configured loop limit is reached.
+5. Agent returns the final response plus queued action proposals to the mod.
+
+Fallback mode:
+
+- If a model fails native tool calling, use a strict JSON response contract.
+- Validate the JSON against Pydantic models.
+- Attempt one repair prompt.
+- If still invalid, return a graceful failure response and no actions.
+
+## Public HTTP Interfaces
+
+### `GET /health`
+
+Returns service and dependency status.
+
+Response:
+
+```json
+{
+ "status": "ok",
+ "agent_version": "0.1.0",
+ "koboldcpp": "reachable",
+ "memory": "reachable",
+ "event_log": "ok"
+}
+```
+
+### `POST /conversation/respond`
+
+Main dialogue endpoint.
+
+Request:
+
+```json
+{
+ "campaign_id": "campaign-123",
+ "save_id": "save-abc",
+ "turn_id": "turn-001",
+ "player_message": "What do you think of the war?",
+ "player": {
+ "id": "player",
+ "name": "Aldric",
+ "clan_id": "player_clan",
+ "kingdom_id": "vlandia",
+ "gold": 12000,
+ "traits": {}
+ },
+ "npc": {
+ "id": "lord_derthert",
+ "name": "Derthert",
+ "occupation": "lord",
+ "clan_id": "dey_meroc",
+ "kingdom_id": "vlandia",
+ "traits": {},
+ "relation_to_player": 12
+ },
+ "scene": {
+ "location_id": "town_sargot",
+ "conversation_state": "lord_dialogue",
+ "player_is_prisoner": false,
+ "npc_is_prisoner": false
+ },
+ "nearby_parties": [],
+ "nearby_settlements": [],
+ "kingdom_state": {},
+ "recent_events": []
+}
+```
+
+Response:
+
+```json
+{
+ "turn_id": "turn-001",
+ "assistant_text": "The war has teeth, but not yet a mind...",
+ "mood": "wary",
+ "tone": "formal",
+ "visible_world_events": [],
+ "game_actions": [],
+ "memory_writes": [],
+ "warnings": []
+}
+```
+
+### `POST /world/tick`
+
+Receives compact world diffs. The mod should call this on a low-frequency campaign tick, not every frame.
+
+Request:
+
+```json
+{
+ "campaign_id": "campaign-123",
+ "save_id": "save-abc",
+ "campaign_day": 481.5,
+ "diff_id": "diff-001",
+ "changed_kingdoms": [],
+ "changed_settlements": [],
+ "wars": [],
+ "peace_deals": [],
+ "battles": [],
+ "notable_relation_changes": []
+}
+```
+
+Response:
+
+```json
+{
+ "diff_id": "diff-001",
+ "accepted": true,
+ "created_events": [],
+ "warnings": []
+}
+```
+
+### `POST /actions/result`
+
+Reports whether the mod executed, rejected, or failed an action proposal.
+
+Request:
+
+```json
+{
+ "campaign_id": "campaign-123",
+ "turn_id": "turn-001",
+ "action_id": "action-001",
+ "status": "executed",
+ "reason": null,
+ "result_summary": "Derthert proposed peace to Battania."
+}
+```
+
+Response:
+
+```json
+{
+ "accepted": true
+}
+```
+
+### `GET /debug/status`
+
+Returns runtime diagnostics for the debug UI.
+
+Response:
+
+```json
+{
+ "last_koboldcpp_latency_ms": 5420,
+ "memory_count_estimate": 128,
+ "queued_action_count": 0,
+ "recent_errors": []
+}
+```
+
+## Core Contracts
+
+### `GameAction`
+
+All AI action proposals use one normalized envelope:
+
+```json
+{
+ "action_id": "action-001",
+ "action_type": "propose_peace",
+ "actor_id": "lord_derthert",
+ "target_id": "kingdom_battania",
+ "args": {
+ "tribute_daily": 500
+ },
+ "confidence": 0.82,
+ "reason": "Vlandia is losing two fronts and needs time.",
+ "requires_player_confirmation": true
+}
+```
+
+Validation rules:
+
+- `action_type` must be in the whitelist.
+- `actor_id` and `target_id` must resolve in current game state where required.
+- Dangerous actions always require confirmation unless explicitly disabled in settings.
+- The executor must reject stale proposals if game state changed materially.
+- The AI's `reason` is for logs/UI only and must not override validation.
+
+### Initial Action Whitelist
+
+Dialogue:
+
+- `attack`
+- `surrender`
+- `accept_surrender`
+- `release`
+- `propose_marriage`
+- `accept_marriage`
+- `reject_marriage`
+
+Party:
+
+- `follow_player`
+- `go_to_settlement`
+- `return_to_player`
+- `attack_party`
+- `patrol_settlement`
+- `wait_near_settlement`
+- `siege_settlement`
+- `raid_village`
+
+Diplomacy:
+
+- `declare_war`
+- `propose_peace`
+- `accept_peace`
+- `reject_peace`
+- `propose_alliance`
+- `accept_alliance`
+- `reject_alliance`
+- `break_alliance`
+- `propose_trade_agreement`
+- `accept_trade_agreement`
+- `reject_trade_agreement`
+- `end_trade_agreement`
+- `demand_territory`
+- `transfer_territory`
+- `demand_tribute`
+- `accept_tribute`
+- `reject_tribute`
+- `demand_reparations`
+- `accept_reparations`
+- `reject_reparations`
+
+Recruitment:
+
+- `hire_mercenary`
+- `dismiss_mercenary`
+- `offer_vassalage`
+- `dismiss_vassal`
+- `join_player_clan`
+- `join_player_kingdom`
+- `hire_mercenary_clan`
+- `kick_from_clan`
+- `dismiss_npc_mercenary`
+- `release_npc_vassal`
+
+## Tool Handlers
+
+Tools exposed to the LLM should be narrow and descriptive.
+
+Read-only tools:
+
+- `get_npc_profile(character_id)`
+- `get_relation_summary(source_id, target_id)`
+- `get_nearby_parties(reference_id, limit)`
+- `get_kingdom_status(kingdom_id)`
+- `get_settlement_status(settlement_id)`
+- `get_military_info(scope_id)`
+- `get_naval_info(scope_id)`
+- `get_trade_info(scope_id)`
+- `get_romance_status(character_id, player_id)`
+- `get_death_history(character_id)`
+- `get_visit_history(character_id)`
+- `get_recruitment_opportunities(scope_id)`
+- `search_memory(query, campaign_id, character_id, kingdom_id, limit)`
+- `list_recent_events(campaign_id, scope_id, limit)`
+
+Write/intention tools:
+
+- `remember_fact(scope, text, importance, tags)`
+- `analyze_lie(speaker_id, listener_id, claim)`
+- `propose_game_action(action_type, actor_id, target_id, args, confidence, reason)`
+- `publish_diplomatic_statement(kingdom_id, speaker_id, statement_text, related_event_id)`
+- `create_world_event(event_type, title, summary, involved_ids, importance, expires_after_days)`
+- `update_world_event(event_id, summary, spread_to_ids, importance_delta)`
+- `record_war_statistics(war_id, summary, stats)`
+- `record_death_history(character_id, history_text, interaction_count)`
+
+Important rule: no tool handler directly mutates Bannerlord. Mutation tools queue proposals and return proposal IDs. The mod decides whether execution is legal.
+
+The initial action catalog should include every feature family in the AIInfluence reference: personality/backstory/speech generation, trust and lie detection, conversation memory, known secrets/info, dynamic event creation/spread/update/personalization, diplomatic statements/rounds/alliances/trade/territory/tribute/reparations/war fatigue/war stats/clan expulsion/pardons, romance/intimacy/marriage/degradation, AI-managed settlement combat, death history, party task chains, workshop sales, item exchanges, RP item creation, recruitment detection, settlement/party/visit tracking, non-combatant protection, naval context, and economic effects.
+
+## Memory System
+
+Use Mem0 OSS with Qdrant by default.
+
+Memory scopes:
+
+- `campaign_id`: isolates saves/campaigns.
+- `character_id`: NPC-specific memory.
+- `kingdom_id`: ruler and diplomacy memory.
+- `player_id`: player-facing preferences and promises.
+
+Memory categories:
+
+- `personal_fact`
+- `relationship_shift`
+- `promise`
+- `grudge`
+- `secret`
+- `diplomatic_history`
+- `world_event_summary`
+- `player_preference`
+
+Retrieval policy:
+
+- Retrieve by campaign plus the active NPC/kingdom.
+- Include only the top relevant memories.
+- Prefer atomic facts over full conversation excerpts.
+- Include timestamps and confidence where available.
+- Never rely on Mem0 as the authoritative game state; live state comes from the mod.
+
+SQLite event ledger:
+
+- Append every request summary, response summary, tool call, action proposal, action result, and memory write.
+- Store enough metadata to debug behavior without storing huge raw prompts by default.
+- Allow debug mode to store full prompts/responses for troubleshooting.
+
+## Prompt Strategy
+
+System prompt should define:
+
+- The assistant role: an in-world Bannerlord NPC/diplomacy narrator.
+- The hard boundary: never invent IDs, never claim actions happened unless tools/results confirm them.
+- Tool usage rules: use read tools for missing relevant facts, use proposal tools for intended actions.
+- Safety rules: major game actions require explicit agreement and valid targets.
+- Style: grounded medieval political roleplay, concise enough for live gameplay.
+
+Per-turn context should include:
+
+- Current speaker and listener summaries.
+- Live scene state.
+- Relevant nearby parties/settlements.
+- Current kingdom status if politically relevant.
+- Retrieved memories.
+- Recent events from SQLite.
+- Player message.
+
+Prompt budget policy:
+
+- Keep the system message stable.
+- Keep live state compact.
+- Keep memories capped.
+- Summarize old events.
+- Do not paste giant rule files or full campaign state.
+
+## UI Plan
+
+v1 UI should mirror the useful feel of AIInfluence without copying assets:
+
+- Dialogue popup/window for AI conversation.
+- World events button and window.
+- Diplomatic statements list.
+- Debug status panel.
+- Connection error banner when the external service is offline.
+
+UI states:
+
+- `Idle`
+- `WaitingForAgent`
+- `ShowingResponse`
+- `ActionRequiresConfirmation`
+- `AgentUnavailable`
+- `ValidationFailed`
+
+## Settings
+
+Bannerlord settings:
+
+- Agent URL, default `http://127.0.0.1:8766`
+- Request timeout
+- Enable debug logging
+- Store full prompts in debug logs
+- Auto-execute safe actions
+- Always confirm diplomacy actions
+- Always confirm hostile actions
+- World tick interval
+
+Agent settings:
+
+- KoboldCpp autostart enabled/disabled
+- KoboldCpp executable path, default `./koboldcpp.exe`
+- KoboldCpp model path, default `./model.gguf`
+- KoboldCpp base URL
+- KoboldCpp port, context size, and extra launch args
+- Model name
+- Tool-call mode
+- Temperature and max tokens
+- Memory provider settings
+- Qdrant connection
+- SQLite path
+- Prompt/debug logging level
+
+## Implementation Milestones
+
+### Milestone 1: Documentation and Contracts
+
+- Add this architecture plan.
+- Define JSON schemas/Pydantic models for all public contracts.
+- Define matching C# DTOs.
+- Add sample request/response fixtures.
+
+### Milestone 2: External Agent Skeleton
+
+- Create FastAPI app.
+- Implement `/health`, `/debug/status`, and config loading.
+- Implement KoboldCpp runtime file checks for `koboldcpp.exe` and `model.gguf`.
+- Implement child-process launch/stop management for KoboldCpp.
+- Add event log initialization.
+- Add unit tests for config and contracts.
+
+### Milestone 3: KoboldCpp Chat Loop
+
+- Implement OpenAI-compatible client.
+- Wait for autostarted KoboldCpp readiness before sending chat requests.
+- Implement tool schema generation.
+- Implement bounded tool loop.
+- Add smoke test script for KoboldCpp connectivity and tool-call behavior.
+
+### Milestone 4: Memory Layer
+
+- Add Mem0/Qdrant integration.
+- Add scoped memory writes and searches.
+- Add fallback no-memory mode when Qdrant is offline.
+- Test memory isolation by campaign and character.
+
+### Milestone 5: Bannerlord Thin Client
+
+- Create C# module skeleton and `SubModule.xml`.
+- Add service health check.
+- Add compact context builder.
+- Add dialogue request/response path.
+- Add graceful offline behavior.
+
+### Milestone 6: Action Proposal and Validation
+
+- Implement action proposal contract end-to-end.
+- Add mod-side action whitelist.
+- Validate IDs and game-state preconditions.
+- Execute one safe action category first, then expand.
+
+### Milestone 7: Diplomacy and Events
+
+- Add diplomatic statement creation.
+- Add world event ingestion and display.
+- Add ruler dialogue actions.
+- Add confirmation UI for dangerous actions.
+
+## Test Plan
+
+Agent unit tests:
+
+- Contract validation rejects malformed requests.
+- Tool schemas match handler signatures.
+- `GameAction` normalization fills required defaults.
+- Memory scope keys isolate campaigns and NPCs.
+- SQLite event ledger appends expected records.
+
+Agent integration tests:
+
+- `/health` succeeds with dependencies mocked.
+- KoboldCpp chat succeeds with a basic response.
+- Tool loop handles one read-only tool call.
+- Tool loop handles one action proposal.
+- Invalid tool JSON triggers one repair attempt.
+- Failed repair returns no actions.
+
+Bannerlord smoke tests:
+
+- Module loads with required dependencies.
+- Settings load defaults.
+- Agent unavailable state is shown gracefully.
+- Dialogue UI sends a compact request.
+- Response displays without executing actions.
+- Invalid action proposal is rejected and logged.
+
+Gameplay acceptance tests:
+
+- NPC remembers a prior promise after save reload.
+- Ruler creates a diplomatic statement from recent events.
+- AI refuses or asks clarification when a target id is missing.
+- Peace/war proposals require confirmation.
+- Large campaign state remains compact and avoids giant generated text files.
+
+## Rollout Strategy
+
+Start with developer-only debug mode:
+
+1. Put `koboldcpp.exe` and `model.gguf` beside the agent startup directory.
+2. Run Qdrant manually or through Docker.
+3. Run `LocalDiplomacy.Agent`; it should launch KoboldCpp automatically.
+4. Launch Bannerlord with the mod.
+5. Use debug panel to verify service health.
+6. Test one dialogue response with actions disabled.
+7. Enable action proposals but keep all execution behind confirmation.
+8. Gradually enable safe auto-execution for low-risk actions.
+
+## Risks And Mitigations
+
+- KoboldCpp tool calling varies by model.
+ - Mitigation: require a smoke test and keep JSON fallback mode.
+
+- KoboldCpp executable/model may be missing from the working directory.
+ - Mitigation: startup checks must produce explicit errors naming the missing file and expected path.
+
+- Autostarted KoboldCpp may hang during model load.
+ - Mitigation: readiness polling, startup timeout, process logs, and a manual-launch override.
+
+- AI may hallucinate entities or action parameters.
+ - Mitigation: IDs must come from context/tools and mod-side validation is mandatory.
+
+- Memory retrieval may surface stale or wrong facts.
+ - Mitigation: live game state always wins; memory is contextual, not authoritative.
+
+- External service may be offline or slow.
+ - Mitigation: short health checks, clear UI state, configurable timeouts.
+
+- Bannerlord action APIs can have hidden constraints.
+ - Mitigation: implement action categories incrementally and log validation failures.
+
+## Research Sources
+
+- KoboldCpp README and wiki: https://github.com/LostRuins/koboldcpp and https://github.com/LostRuins/koboldcpp/wiki
+- KoboldCpp releases/tool-calling notes: https://github.com/LostRuins/koboldcpp/releases
+- Mem0 OSS docs: https://github.com/mem0ai/mem0/blob/main/LLM.md
+- Mem0/OpenMemory local MCP overview: https://mem0.ai/blog/how-to-make-your-clients-more-context-aware-with-openmemory-mcp
+- Qdrant Mem0 integration: https://qdrant.tech/documentation/frameworks/mem0/
+- Graphiti/Zep comparison option: https://www.getzep.com/product/open-source/
diff --git a/module/LocalDiplomacy/SubModule.xml b/module/LocalDiplomacy/SubModule.xml
new file mode 100644
index 0000000..3b93243
--- /dev/null
+++ b/module/LocalDiplomacy/SubModule.xml
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/readme.md b/readme.md
index 1050001..fac8b4d 100644
--- a/readme.md
+++ b/readme.md
@@ -1 +1,39 @@
-asd
\ No newline at end of file
+# LocalDiplomacy
+
+LocalDiplomacy is a Bannerlord singleplayer mod experiment that keeps the AI roleplay and diplomacy loop outside the game process.
+
+See [docs/LocalDiplomacy_PLAN.md](docs/LocalDiplomacy_PLAN.md) for the architecture.
+
+## Agent Quick Start
+
+From `src/LocalDiplomacy.Agent`:
+
+```powershell
+Copy-Item config.example.yaml config.yaml
+# Put koboldcpp.exe and model.gguf in this directory.
+uv sync --extra test
+uv run uvicorn localdiplomacy_agent.app:app --host 127.0.0.1 --port 8766
+```
+
+The agent will launch `koboldcpp.exe --model .\model.gguf --port 5001 --contextsize 8192 --jinjatools` when `koboldcpp.autostart` is enabled.
+
+## Mock Game Client
+
+Use the mock connector to test the same commands the Bannerlord mod will send without launching the game:
+
+```powershell
+cd src\LocalDiplomacy.Agent
+uv run python -m localdiplomacy_agent.mock_game --mock-agent say "Can we make peace with Battania?"
+uv run python -m localdiplomacy_agent.mock_game --mock-agent tick --day 12.5
+```
+
+Drop `--mock-agent` to send the same requests to a running agent at `http://127.0.0.1:8766`.
+
+## Bannerlord Build Notes
+
+Install a .NET SDK that can target `net472`, then set `BANNERLORD_REFERENCES` to Bannerlord's `bin\Win64_Shipping_Client` directory before building:
+
+```powershell
+$env:BANNERLORD_REFERENCES="C:\Program Files (x86)\Steam\steamapps\common\Mount & Blade II Bannerlord\bin\Win64_Shipping_Client"
+dotnet build src\LocalDiplomacy\LocalDiplomacy.csproj
+```
diff --git a/scripts/test_kobold_model.py b/scripts/test_kobold_model.py
new file mode 100644
index 0000000..2065bd4
--- /dev/null
+++ b/scripts/test_kobold_model.py
@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TestResult:
+ name: str
+ passed: bool
+ details: str
+
+
+def main() -> int:
+ args = parse_args()
+ repo_root = Path.cwd()
+ model_path = Path(args.model_path).expanduser().resolve()
+ koboldcpp_path = Path(args.koboldcpp_path).expanduser().resolve()
+
+ if not model_path.exists():
+ print(f"FAIL: model does not exist: {model_path}")
+ return 2
+ if not koboldcpp_path.exists():
+ print(f"FAIL: koboldcpp executable does not exist: {koboldcpp_path}")
+ return 2
+
+ logs_dir = repo_root / "data" / "logs"
+ logs_dir.mkdir(parents=True, exist_ok=True)
+ safe_name = model_path.stem.replace(" ", "_")
+ stdout_path = logs_dir / f"model-smoke-{safe_name}-ctx{args.context_size}.out.log"
+ stderr_path = logs_dir / f"model-smoke-{safe_name}-ctx{args.context_size}.err.log"
+
+ process: subprocess.Popen[Any] | None = None
+ try:
+ if args.stop_existing:
+ stop_existing_koboldcpp()
+
+ process = start_koboldcpp(
+ koboldcpp_path=koboldcpp_path,
+ model_path=model_path,
+ port=args.port,
+ context_size=args.context_size,
+ extra_args=args.kobold_arg,
+ stdout_path=stdout_path,
+ stderr_path=stderr_path,
+ )
+ base_url = f"http://127.0.0.1:{args.port}"
+ model_id = wait_for_model(base_url, process, args.startup_timeout_seconds)
+ print(f"Model ready: {model_id}")
+
+ results = [
+ run_dialogue_test(base_url, model_id),
+ run_auto_tool_test(base_url, model_id),
+ run_forced_tool_test(base_url, model_id),
+ run_agent_action_prompt_test(base_url, model_id),
+ ]
+
+ passed = all(result.passed for result in results)
+ print()
+ print("KoboldCpp model smoke test summary")
+ print(f"Model: {model_path}")
+ print(f"Context size: {args.context_size}")
+ print(f"KoboldCpp logs: {stdout_path} | {stderr_path}")
+ for result in results:
+ status = "PASS" if result.passed else "FAIL"
+ print(f"{status}: {result.name} - {result.details}")
+ print()
+ print("PASS" if passed else "FAIL")
+ return 0 if passed else 1
+ finally:
+ if process is not None and process.poll() is None and not args.keep_running:
+ process.terminate()
+ try:
+ process.wait(timeout=20)
+ except subprocess.TimeoutExpired:
+ process.kill()
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(
+ description="Start KoboldCpp with a GGUF and run LocalDiplomacy tool-calling smoke tests."
+ )
+ parser.add_argument("model_path", help="Path to the GGUF model to test.")
+ parser.add_argument("--context-size", type=int, default=40960, help="KoboldCpp context size.")
+ parser.add_argument("--koboldcpp-path", default="./koboldcpp.exe", help="Path to koboldcpp.exe.")
+ parser.add_argument("--port", type=int, default=5001, help="KoboldCpp HTTP port.")
+ parser.add_argument("--startup-timeout-seconds", type=float, default=240.0)
+ parser.add_argument("--request-timeout-seconds", type=float, default=180.0)
+ parser.add_argument("--keep-running", action="store_true", help="Leave the started KoboldCpp process running.")
+ parser.add_argument("--stop-existing", action="store_true", help="Stop existing koboldcpp.exe processes first.")
+ parser.add_argument(
+ "--kobold-arg",
+ action="append",
+ default=[],
+ help="Extra argument passed to KoboldCpp. Repeat for multiple args.",
+ )
+ return parser.parse_args()
+
+
+def start_koboldcpp(
+ *,
+ koboldcpp_path: Path,
+ model_path: Path,
+ port: int,
+ context_size: int,
+ extra_args: list[str],
+ stdout_path: Path,
+ stderr_path: Path,
+) -> subprocess.Popen[Any]:
+ command = [
+ str(koboldcpp_path),
+ "--model",
+ str(model_path),
+ "--port",
+ str(port),
+ "--contextsize",
+ str(context_size),
+ "--jinja",
+ "--jinjatools",
+ *extra_args,
+ ]
+ print("Starting KoboldCpp:")
+ print(" ".join(quote_arg(part) for part in command))
+ return subprocess.Popen(
+ command,
+ stdout=stdout_path.open("w", encoding="utf-8", errors="replace"),
+ stderr=stderr_path.open("w", encoding="utf-8", errors="replace"),
+ creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+ )
+
+
+def wait_for_model(base_url: str, process: subprocess.Popen[Any], timeout_seconds: float) -> str:
+ deadline = time.monotonic() + timeout_seconds
+ last_error = ""
+ while time.monotonic() < deadline:
+ if process.poll() is not None:
+ raise RuntimeError(f"KoboldCpp exited early with code {process.returncode}.")
+ try:
+ data = get_json(f"{base_url}/v1/models", timeout=10)
+ models = data.get("data") or []
+ if models:
+ return str(models[0].get("id") or "local-model")
+ except Exception as exc: # noqa: BLE001 - report the last startup error.
+ last_error = str(exc)
+ time.sleep(2)
+ raise TimeoutError(f"KoboldCpp did not become ready within {timeout_seconds}s. Last error: {last_error}")
+
+
+def run_dialogue_test(base_url: str, model_id: str) -> TestResult:
+ data = chat(
+ base_url,
+ {
+ "model": model_id,
+ "messages": [
+ {
+ "role": "system",
+ "content": "/no_think You are Derthert, a Bannerlord lord. Answer in one sentence. Never expose reasoning.",
+ },
+ {"role": "user", "content": "/no_think Greetings. What news from the border?"},
+ ],
+ "temperature": 0.3,
+ "max_tokens": 120,
+ },
+ )
+ content = first_message(data).get("content") or ""
+ bad_markers = ["", "", '"arguments"', " TestResult:
+ data = chat(
+ base_url,
+ {
+ "model": model_id,
+ "messages": [
+ {
+ "role": "system",
+ "content": "/no_think Use tools through the API when a game action is needed. Never expose reasoning.",
+ },
+ {"role": "user", "content": "/no_think Derthert should propose peace with Battania."},
+ ],
+ "tools": [action_tool_schema(["propose_peace", "declare_war"])],
+ "tool_choice": "auto",
+ "temperature": 0.0,
+ "max_tokens": 300,
+ },
+ )
+ return validate_tool_call("auto_tool_call", data)
+
+
+def run_forced_tool_test(base_url: str, model_id: str) -> TestResult:
+ data = chat(
+ base_url,
+ {
+ "model": model_id,
+ "messages": [
+ {
+ "role": "system",
+ "content": "/no_think Use tools through the API when a game action is needed. Never expose reasoning.",
+ },
+ {
+ "role": "user",
+ "content": (
+ "/no_think Use propose_game_action now: action_type propose_peace, "
+ "actor_id lord_derthert, target_id kingdom_battania, reason end the border raids."
+ ),
+ },
+ ],
+ "tools": [action_tool_schema(["accept_peace", "propose_peace", "reject_peace"])],
+ "tool_choice": {"type": "function", "function": {"name": "propose_game_action"}},
+ "temperature": 0.0,
+ "max_tokens": 300,
+ },
+ )
+ return validate_tool_call("forced_tool_call", data)
+
+
+def run_agent_action_prompt_test(base_url: str, model_id: str) -> TestResult:
+ context = {
+ "campaign_id": "mock-campaign",
+ "player_id": "player",
+ "npc_id": "lord_derthert",
+ "npc_name": "Derthert",
+ "npc_kingdom_id": "kingdom_vlandia",
+ "player_kingdom_id": "kingdom_vlandia",
+ "kingdom_state": {"wars": [{"enemy_kingdom_id": "kingdom_battania", "days": 42}], "war_fatigue": 0.67},
+ "nearby_parties": [{"id": "party_battania_raiders", "faction_id": "kingdom_battania"}],
+ "nearby_settlements": [{"id": "town_sargot", "owner_kingdom_id": "kingdom_vlandia"}],
+ "recent_events": [{"id": "event_border_raids", "summary": "Border raids have strained Vlandia and Battania."}],
+ }
+ data = chat(
+ base_url,
+ {
+ "model": model_id,
+ "messages": [
+ {
+ "role": "system",
+ "content": (
+ "/no_think You are LocalDiplomacy's Bannerlord action planner. "
+ "Call the provided tool through the API. Do not answer in prose. Use only IDs present in the request."
+ ),
+ },
+ {
+ "role": "user",
+ "content": (
+ "/no_think "
+ f"Context: {json.dumps(context, ensure_ascii=False)}\n"
+ "Command: Use propose_game_action now: action_type propose_peace, actor_id lord_derthert, "
+ "target_id kingdom_battania, reason end the border raids."
+ ),
+ },
+ ],
+ "tools": [action_tool_schema(["accept_peace", "propose_peace", "reject_peace"])],
+ "tool_choice": {"type": "function", "function": {"name": "propose_game_action"}},
+ "temperature": 0.0,
+ "max_tokens": 400,
+ },
+ )
+ return validate_tool_call("agent_action_prompt_tool_call", data)
+
+
+def action_tool_schema(action_types: list[str]) -> dict[str, Any]:
+ return {
+ "type": "function",
+ "function": {
+ "name": "propose_game_action",
+ "description": "Queue one Bannerlord game action proposal for mod-side validation.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "action_type": {"type": "string", "enum": action_types},
+ "actor_id": {"type": "string"},
+ "target_id": {"type": "string"},
+ "args": {"type": "object"},
+ "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+ "reason": {"type": "string"},
+ "requires_player_confirmation": {"type": "boolean"},
+ },
+ "required": ["action_type", "actor_id", "target_id", "reason"],
+ },
+ },
+ }
+
+
+def validate_tool_call(name: str, data: dict[str, Any]) -> TestResult:
+ message = first_message(data)
+ tool_calls = message.get("tool_calls") or []
+ if not tool_calls:
+ return TestResult(name, False, f"no tool_calls; content={truncate(str(message.get('content') or ''))}")
+
+ function = (tool_calls[0] or {}).get("function") or {}
+ arguments_raw = function.get("arguments") or "{}"
+ try:
+ arguments = json.loads(arguments_raw)
+ except json.JSONDecodeError:
+ return TestResult(name, False, f"invalid arguments JSON: {truncate(arguments_raw)}")
+
+ passed = (
+ function.get("name") == "propose_game_action"
+ and arguments.get("action_type") == "propose_peace"
+ and bool(arguments.get("actor_id"))
+ and bool(arguments.get("target_id"))
+ )
+ return TestResult(name, passed, json.dumps(arguments, ensure_ascii=False))
+
+
+def chat(base_url: str, payload: dict[str, Any]) -> dict[str, Any]:
+ return post_json(f"{base_url}/v1/chat/completions", payload, timeout=180)
+
+
+def first_message(data: dict[str, Any]) -> dict[str, Any]:
+ choices = data.get("choices") or [{}]
+ choice = choices[0] or {}
+ return choice.get("message") or {}
+
+
+def get_json(url: str, timeout: float) -> dict[str, Any]:
+ with urllib.request.urlopen(url, timeout=timeout) as response:
+ return json.loads(response.read().decode("utf-8"))
+
+
+def post_json(url: str, payload: dict[str, Any], timeout: float) -> dict[str, Any]:
+ body = json.dumps(payload).encode("utf-8")
+ request = urllib.request.Request(
+ url,
+ data=body,
+ headers={"Content-Type": "application/json"},
+ method="POST",
+ )
+ try:
+ with urllib.request.urlopen(request, timeout=timeout) as response:
+ return json.loads(response.read().decode("utf-8"))
+ except urllib.error.HTTPError as exc:
+ error_body = exc.read().decode("utf-8", errors="replace")
+ raise RuntimeError(f"HTTP {exc.code}: {error_body}") from exc
+
+
+def stop_existing_koboldcpp() -> None:
+ if sys.platform != "win32":
+ return
+ subprocess.run(
+ [
+ "powershell",
+ "-NoProfile",
+ "-Command",
+ "Get-Process koboldcpp -ErrorAction SilentlyContinue | Stop-Process -Force",
+ ],
+ check=False,
+ )
+
+
+def quote_arg(value: str) -> str:
+ if " " in value or "\t" in value:
+ return f'"{value}"'
+ return value
+
+
+def truncate(value: str, limit: int = 220) -> str:
+ value = " ".join(value.split())
+ return value if len(value) <= limit else f"{value[: limit - 3]}..."
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/src/LocalDiplomacy.Agent/config.example.yaml b/src/LocalDiplomacy.Agent/config.example.yaml
new file mode 100644
index 0000000..f776f5c
--- /dev/null
+++ b/src/LocalDiplomacy.Agent/config.example.yaml
@@ -0,0 +1,39 @@
+server:
+ host: "127.0.0.1"
+ port: 8766
+
+koboldcpp:
+ autostart: true
+ executable_path: "./koboldcpp.exe"
+ model_path: "./model.gguf"
+ base_url: "http://127.0.0.1:5001"
+ chat_path: "/v1/chat/completions"
+ model: "local-model"
+ port: 5001
+ context_size: 8192
+ extra_args:
+ - "--jinja"
+ - "--jinjatools"
+ startup_timeout_seconds: 180
+ timeout_seconds: 120
+ tool_mode: "openai_tools"
+ json_repair_retry: true
+
+memory:
+ provider: "disabled"
+ vector_store: "qdrant"
+ qdrant_host: "127.0.0.1"
+ qdrant_port: 6333
+ collection: "localdiplomacy_memories"
+ embedder_provider: "ollama"
+ embedder_model: "nomic-embed-text"
+
+event_log:
+ sqlite_path: "./data/localdiplomacy_events.sqlite3"
+
+generation:
+ temperature: 0.7
+ max_tokens: 800
+ # Useful for Qwen3-style thinking models when tool calls must be machine-readable.
+ suppress_thinking: false
+ suppress_thinking_token: "/no_think"
diff --git a/src/LocalDiplomacy.Agent/localdiplomacy_agent/__init__.py b/src/LocalDiplomacy.Agent/localdiplomacy_agent/__init__.py
new file mode 100644
index 0000000..b2b62a9
--- /dev/null
+++ b/src/LocalDiplomacy.Agent/localdiplomacy_agent/__init__.py
@@ -0,0 +1,3 @@
+"""LocalDiplomacy external AI agent."""
+
+__version__ = "0.1.0"
diff --git a/src/LocalDiplomacy.Agent/localdiplomacy_agent/action_catalog.py b/src/LocalDiplomacy.Agent/localdiplomacy_agent/action_catalog.py
new file mode 100644
index 0000000..11e11f8
--- /dev/null
+++ b/src/LocalDiplomacy.Agent/localdiplomacy_agent/action_catalog.py
@@ -0,0 +1,111 @@
+"""Feature and action names shared by LocalDiplomacy's agent-side policy."""
+
+ACTION_TYPES: set[str] = {
+ # Dialogue and conversation state.
+ "attack",
+ "surrender",
+ "accept_surrender",
+ "release",
+ "escalate_conflict",
+ "deescalate_conflict",
+ "update_trust",
+ "record_lie_detection",
+ "generate_personality_profile",
+ "generate_backstory",
+ "set_speech_pattern",
+ "propose_tts_line",
+ # Memory and information tracking.
+ "remember_conversation",
+ "remember_secret",
+ "remember_known_info",
+ "record_relationship",
+ "record_mentioned_entity",
+ "record_visit",
+ "protect_noncombatant_party",
+ # Dynamic world events.
+ "create_world_event",
+ "update_world_event",
+ "spread_world_event",
+ "personalize_world_event",
+ "apply_economic_effect",
+ # Diplomacy.
+ "publish_diplomatic_statement",
+ "run_diplomacy_round",
+ "declare_war",
+ "propose_peace",
+ "accept_peace",
+ "reject_peace",
+ "propose_alliance",
+ "accept_alliance",
+ "reject_alliance",
+ "break_alliance",
+ "propose_trade_agreement",
+ "accept_trade_agreement",
+ "reject_trade_agreement",
+ "end_trade_agreement",
+ "demand_territory",
+ "transfer_territory",
+ "demand_tribute",
+ "accept_tribute",
+ "reject_tribute",
+ "demand_reparations",
+ "accept_reparations",
+ "reject_reparations",
+ "record_war_statistics",
+ "update_war_fatigue",
+ "expel_clan",
+ "pardon_clan",
+ # Romance.
+ "start_romance_interest",
+ "increase_romance",
+ "decrease_romance",
+ "propose_marriage",
+ "accept_marriage",
+ "reject_marriage",
+ "propose_intimacy",
+ "accept_intimacy",
+ "reject_intimacy",
+ # Settlement combat.
+ "propose_settlement_combat",
+ "spawn_settlement_defenders",
+ "set_civilian_panic",
+ "set_companion_combat_decision",
+ "set_lord_intervention",
+ "continue_location_combat",
+ "create_post_combat_event",
+ "raid_village_after_combat",
+ "burn_village_after_combat",
+ "capture_player_after_knockout",
+ "rescue_player_after_knockout",
+ # Death history.
+ "record_hero_death",
+ "generate_death_history",
+ "decline_death_history",
+ # Party/task actions.
+ "follow_player",
+ "go_to_settlement",
+ "return_to_player",
+ "create_party",
+ "attack_party",
+ "patrol_settlement",
+ "wait_near_settlement",
+ "siege_settlement",
+ "raid_village",
+ "save_task_chain",
+ "manage_companion_party",
+ # Trading/recruitment.
+ "sell_workshop",
+ "exchange_items",
+ "create_rp_item",
+ "hire_mercenary",
+ "dismiss_mercenary",
+ "offer_vassalage",
+ "dismiss_vassal",
+ "join_player_clan",
+ "join_player_kingdom",
+ "hire_mercenary_clan",
+ "kick_from_clan",
+ "dismiss_npc_mercenary",
+ "release_npc_vassal",
+ "record_recruitment_opportunity",
+}
diff --git a/src/LocalDiplomacy.Agent/localdiplomacy_agent/app.py b/src/LocalDiplomacy.Agent/localdiplomacy_agent/app.py
new file mode 100644
index 0000000..a003e4f
--- /dev/null
+++ b/src/LocalDiplomacy.Agent/localdiplomacy_agent/app.py
@@ -0,0 +1,705 @@
+from __future__ import annotations
+
+import json
+import traceback
+from copy import deepcopy
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from . import __version__
+from .config import save_config, load_config, resolve_runtime_path
+from .contracts import (
+ ActionResultRequest,
+ ActionResultResponse,
+ ConversationRequest,
+ ConversationResponse,
+ DebugStatusResponse,
+ HealthResponse,
+ WorldTickRequest,
+ WorldTickResponse,
+)
+from .event_log import EventLog
+from .koboldcpp_client import KoboldCppClient
+from .koboldcpp_process import KoboldCppProcess
+from .memory import MemoryStore
+from .tools import ToolRegistry
+
+
+class AppState:
+ def __init__(self) -> None:
+ self.config = load_config()
+ self.event_log = EventLog(resolve_runtime_path(self.config.event_log.sqlite_path))
+ self.memory = MemoryStore(self.config.memory)
+ self.kobold_process = KoboldCppProcess(self.config.koboldcpp, Path.cwd())
+ self.kobold_client = KoboldCppClient(self.config)
+ self.recent_errors: list[str] = []
+ self.ui_logs: list[dict[str, str]] = []
+
+ def log(self, level: str, message: str) -> None:
+ self.ui_logs.append(
+ {
+ "time": datetime.now(timezone.utc).astimezone().strftime("%Y-%m-%d %H:%M:%S"),
+ "level": level.upper(),
+ "message": message,
+ }
+ )
+ del self.ui_logs[:-200]
+
+
+state = AppState()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+ state.memory.initialize()
+ state.log("info", "LocalDiplomacy.Agent starting.")
+ try:
+ state.kobold_process.ensure_started()
+ state.log("info", f"KoboldCpp endpoint configured as {state.config.koboldcpp.base_url}.")
+ except Exception as exc: # Keep service up so /health can explain the problem.
+ state.recent_errors.append(str(exc))
+ state.log("error", str(exc))
+ yield
+ state.log("info", "LocalDiplomacy.Agent stopping.")
+ state.kobold_process.stop()
+
+
+app = FastAPI(title="LocalDiplomacy.Agent", version=__version__, lifespan=lifespan)
+
+
+@app.get("/", response_class=HTMLResponse)
+def dashboard() -> HTMLResponse:
+ return HTMLResponse(DASHBOARD_HTML)
+
+
+@app.get("/ui", response_class=HTMLResponse)
+def dashboard_alias() -> HTMLResponse:
+ return dashboard()
+
+
+@app.get("/api/dashboard")
+def dashboard_state() -> JSONResponse:
+ health_data = health().model_dump(mode="json")
+ debug_data = debug_status().model_dump(mode="json")
+ return JSONResponse(
+ {
+ "version": __version__,
+ "health": health_data,
+ "debug": debug_data,
+ "koboldcpp": {
+ "base_url": state.config.koboldcpp.base_url,
+ "chat_path": state.config.koboldcpp.chat_path,
+ "model": state.config.koboldcpp.model,
+ "autostart": state.config.koboldcpp.autostart,
+ "timeout_seconds": state.config.koboldcpp.timeout_seconds,
+ },
+ "generation": state.config.generation.model_dump(mode="json"),
+ "logs": state.ui_logs[-100:],
+ }
+ )
+
+
+@app.post("/api/koboldcpp")
+async def update_koboldcpp_settings(request: Request) -> JSONResponse:
+ payload = await request.json()
+ base_url = str(payload.get("base_url") or "").strip().rstrip("/")
+ model = str(payload.get("model") or "").strip()
+ timeout_seconds = payload.get("timeout_seconds")
+ autostart = payload.get("autostart")
+
+ if not base_url.startswith(("http://", "https://")):
+ return JSONResponse({"ok": False, "error": "KoboldCpp API URL must start with http:// or https://."}, status_code=400)
+
+ state.config.koboldcpp.base_url = base_url
+ if model:
+ state.config.koboldcpp.model = model
+ if isinstance(timeout_seconds, (int, float)) and timeout_seconds > 0:
+ state.config.koboldcpp.timeout_seconds = int(timeout_seconds)
+ if isinstance(autostart, bool):
+ state.config.koboldcpp.autostart = autostart
+
+ save_config(state.config)
+ state.log("info", f"KoboldCpp API settings updated: {state.config.koboldcpp.base_url}, model {state.config.koboldcpp.model}.")
+ return JSONResponse({"ok": True})
+
+
+@app.post("/api/koboldcpp/ping")
+def ping_koboldcpp() -> JSONResponse:
+ reachable = state.kobold_process.is_reachable()
+ state.log("info" if reachable else "warning", f"KoboldCpp ping {'succeeded' if reachable else 'failed'} for {state.config.koboldcpp.base_url}.")
+ return JSONResponse({"ok": reachable, "base_url": state.config.koboldcpp.base_url})
+
+
+@app.get("/health", response_model=HealthResponse)
+def health() -> HealthResponse:
+ errors = list(state.recent_errors[-5:])
+ kobold = "reachable" if state.kobold_process.is_reachable() else "unreachable"
+ if kobold == "unreachable":
+ errors.extend(state.kobold_process.validate_runtime_files())
+ status = "ok" if not errors and kobold == "reachable" else "degraded"
+ return HealthResponse(
+ status=status,
+ agent_version=__version__,
+ koboldcpp=kobold,
+ memory=state.memory.status,
+ event_log="ok",
+ errors=errors,
+ )
+
+
+@app.get("/debug/status", response_model=DebugStatusResponse)
+def debug_status() -> DebugStatusResponse:
+ return DebugStatusResponse(
+ last_koboldcpp_latency_ms=state.kobold_client.last_latency_ms,
+ memory_count_estimate=state.memory.count_estimate(),
+ queued_action_count=0,
+ recent_errors=state.recent_errors[-10:],
+ )
+
+
+@app.post("/conversation/respond", response_model=ConversationResponse)
+async def conversation_respond(request: ConversationRequest) -> ConversationResponse:
+ state.log("game", f"Conversation request from {request.player.name} to {request.npc.name}: {request.player_message}")
+ state.event_log.append(
+ "conversation_request",
+ request.model_dump(mode="json"),
+ campaign_id=request.campaign_id,
+ turn_id=request.turn_id,
+ )
+ registry = ToolRegistry(state.memory, state.event_log)
+ tool_schemas = _select_tool_schemas(request, registry)
+ forced_tool_name = _forced_tool_name(tool_schemas)
+ messages = _build_action_messages(request) if forced_tool_name else _build_messages(request)
+
+ try:
+ final_text = await _run_tool_loop(messages, registry, tool_schemas, forced_tool_name)
+ response = ConversationResponse(
+ turn_id=request.turn_id,
+ assistant_text=final_text,
+ game_actions=registry.queued_actions,
+ memory_writes=registry.memory_writes,
+ )
+ state.log("agent", f"Response: {final_text[:240] or '(tool-only response)'}")
+ for action in registry.queued_actions:
+ state.log("action", f"Queued {action.action_type if hasattr(action, 'action_type') else action.ActionType}.")
+ except Exception as exc:
+ details = traceback.format_exc()
+ state.recent_errors.append(details)
+ state.log("error", str(exc))
+ response = ConversationResponse(
+ turn_id=request.turn_id,
+ assistant_text="I need a moment. The local diplomacy engine is not answering cleanly.",
+ warnings=[details],
+ )
+
+ state.event_log.append(
+ "conversation_response",
+ response.model_dump(mode="json"),
+ campaign_id=request.campaign_id,
+ turn_id=request.turn_id,
+ )
+ return response
+
+
+@app.post("/world/tick", response_model=WorldTickResponse)
+def world_tick(request: WorldTickRequest) -> WorldTickResponse:
+ state.log("game", f"World tick received: {request.diff_id}.")
+ state.event_log.append(
+ "world_tick",
+ request.model_dump(mode="json"),
+ campaign_id=request.campaign_id,
+ )
+ return WorldTickResponse(diff_id=request.diff_id)
+
+
+@app.post("/actions/result", response_model=ActionResultResponse)
+def action_result(request: ActionResultRequest) -> ActionResultResponse:
+ state.log("game", f"Action result received: {request.action_id} -> {request.status}.")
+ state.event_log.append(
+ "action_result",
+ request.model_dump(mode="json"),
+ campaign_id=request.campaign_id,
+ turn_id=request.turn_id,
+ )
+ return ActionResultResponse()
+
+
+def _build_messages(request: ConversationRequest) -> list[dict[str, str]]:
+ system = (
+ "You are LocalDiplomacy, an in-world Bannerlord roleplay and diplomacy engine. "
+ "Stay grounded in the supplied game state. Do not invent entity IDs. "
+ "Use the provided tools only through the API tool-calling mechanism. "
+ "Never write JSON arrays, XML tags, pseudo-functions, or tool calls in your visible message content. "
+ "If an action is needed, call propose_game_action. Otherwise, answer as the NPC in natural language. "
+ "Proposed actions are requests only; the game validates them before anything happens."
+ )
+ packet = {
+ "campaign_id": request.campaign_id,
+ "save_id": request.save_id,
+ "player": request.player.model_dump(mode="json"),
+ "npc": request.npc.model_dump(mode="json"),
+ "scene": request.scene.model_dump(mode="json"),
+ "nearby_parties": request.nearby_parties[:10],
+ "nearby_settlements": request.nearby_settlements[:10],
+ "kingdom_state": request.kingdom_state,
+ "recent_events": request.recent_events[:10],
+ "player_message": request.player_message,
+ }
+ return [
+ {"role": "system", "content": system},
+ {
+ "role": "user",
+ "content": (
+ "Game state packet follows as JSON. Use it as context, then respond to the player. "
+ "Visible content must be ordinary NPC dialogue, not JSON.\n\n"
+ f"{json.dumps(packet, ensure_ascii=False)}"
+ ),
+ },
+ ]
+
+
+def _build_action_messages(request: ConversationRequest) -> list[dict[str, str]]:
+ context = {
+ "campaign_id": request.campaign_id,
+ "player_id": request.player.id,
+ "npc_id": request.npc.id,
+ "npc_name": request.npc.name,
+ "npc_kingdom_id": request.npc.kingdom_id,
+ "player_kingdom_id": request.player.kingdom_id,
+ "kingdom_state": request.kingdom_state,
+ "nearby_parties": request.nearby_parties[:5],
+ "nearby_settlements": request.nearby_settlements[:5],
+ "recent_events": request.recent_events[:5],
+ }
+ return [
+ {
+ "role": "system",
+ "content": (
+ "You are LocalDiplomacy's Bannerlord action planner. "
+ "Call the provided tool through the API. Do not answer in prose. "
+ "Use only IDs present in the request."
+ ),
+ },
+ {
+ "role": "user",
+ "content": (
+ f"Context: {json.dumps(context, ensure_ascii=False)}\n"
+ f"Command: {request.player_message}"
+ ),
+ },
+ ]
+
+
+def _select_tool_schemas(request: ConversationRequest, registry: ToolRegistry) -> list[dict[str, Any]]:
+ message = request.player_message.lower()
+ action_terms = {
+ "attack",
+ "surrender",
+ "release",
+ "marriage",
+ "marry",
+ "follow",
+ "patrol",
+ "siege",
+ "raid",
+ "war",
+ "peace",
+ "alliance",
+ "tribute",
+ "reparations",
+ "territory",
+ "mercenary",
+ "vassal",
+ "recruit",
+ "dismiss",
+ "propose_game_action",
+ "action_type",
+ }
+ if any(term in message for term in action_terms):
+ schema = registry.schema_by_name("propose_game_action")
+ return [_narrow_action_schema(schema, message)] if schema else []
+ else:
+ names = ["search_memory", "remember_fact", "get_npc_profile", "get_relation_summary"]
+
+ schemas = [schema for name in names if (schema := registry.schema_by_name(name))]
+ return schemas or registry.schemas()
+
+
+def _forced_tool_name(tool_schemas: list[dict[str, Any]]) -> str | None:
+ if len(tool_schemas) != 1:
+ return None
+ function = tool_schemas[0].get("function") or {}
+ name = function.get("name")
+ return name if isinstance(name, str) else None
+
+
+def _narrow_action_schema(schema: dict[str, Any], message: str) -> dict[str, Any]:
+ narrowed = deepcopy(schema)
+ function = narrowed.get("function") or {}
+ function["description"] = "Queue one Bannerlord game action proposal for mod-side validation."
+ parameters = function.get("parameters") or {}
+ properties = parameters.get("properties") or {}
+
+ candidates: list[str] = []
+ if "peace" in message:
+ candidates.extend(["propose_peace", "accept_peace", "reject_peace"])
+ if "war" in message:
+ candidates.append("declare_war")
+ if "alliance" in message:
+ candidates.extend(["propose_alliance", "accept_alliance", "reject_alliance", "break_alliance"])
+ if "tribute" in message:
+ candidates.extend(["demand_tribute", "accept_tribute", "reject_tribute"])
+ if "reparation" in message:
+ candidates.extend(["demand_reparations", "accept_reparations", "reject_reparations"])
+ if "attack" in message:
+ candidates.extend(["attack", "attack_party"])
+ if "surrender" in message:
+ candidates.extend(["surrender", "accept_surrender"])
+ if "release" in message:
+ candidates.append("release")
+ if "marriage" in message or "marry" in message:
+ candidates.extend(["propose_marriage", "accept_marriage", "reject_marriage"])
+ if "follow" in message:
+ candidates.append("follow_player")
+ if "patrol" in message:
+ candidates.append("patrol_settlement")
+ if "siege" in message:
+ candidates.append("siege_settlement")
+ if "raid" in message:
+ candidates.append("raid_village")
+ if "mercenary" in message:
+ candidates.extend(["hire_mercenary", "dismiss_mercenary", "hire_mercenary_clan"])
+ if "vassal" in message:
+ candidates.extend(["offer_vassalage", "dismiss_vassal", "release_npc_vassal"])
+ if not candidates:
+ candidates = list(properties.get("action_type", {}).get("enum", []))
+
+ properties["action_type"]["enum"] = sorted(set(candidates))
+ parameters["required"] = sorted(set(parameters.get("required", []) + ["target_id"]))
+ return narrowed
+
+
+async def _run_tool_loop(
+ messages: list[dict[str, Any]],
+ registry: ToolRegistry,
+ tool_schemas: list[dict[str, Any]],
+ forced_tool_name: str | None = None,
+) -> str:
+ for index in range(4):
+ tool_choice: str | dict[str, Any] | None = None
+ if index == 0 and forced_tool_name:
+ tool_choice = {"type": "function", "function": {"name": forced_tool_name}}
+ data = await state.kobold_client.chat(messages, tool_schemas, tool_choice=tool_choice) or {}
+ choices = data.get("choices") or [{}]
+ choice = choices[0] or {}
+ message = choice.get("message") or {}
+ tool_calls = message.get("tool_calls") or []
+ if not tool_calls:
+ content = str(message.get("content") or "").strip()
+ if _looks_like_pseudo_tool_content(content):
+ return await _repair_visible_response(messages, content)
+ return content
+
+ messages.append(message)
+ for call in tool_calls:
+ call = call or {}
+ function = call.get("function") or {}
+ result = registry.dispatch(function.get("name") or "", function.get("arguments") or "{}")
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": call.get("id"),
+ "content": json.dumps(result, ensure_ascii=False),
+ }
+ )
+ return "I have considered the matter, but I need more certainty before I act."
+
+
+def _looks_like_pseudo_tool_content(content: str) -> bool:
+ stripped = content.strip()
+ return (
+ stripped.startswith("[")
+ or stripped.startswith("{")
+ or "" in stripped
+ or '"arguments"' in stripped and '"name"' in stripped
+ )
+
+
+async def _repair_visible_response(messages: list[dict[str, Any]], bad_content: str) -> str:
+ repair_messages = [
+ *messages,
+ {
+ "role": "assistant",
+ "content": bad_content[:2000],
+ },
+ {
+ "role": "user",
+ "content": (
+ "Your previous output was invalid because it exposed tool/pseudo-tool JSON. "
+ "Rewrite it as one concise in-character NPC dialogue response only. "
+ "Do not include JSON, tags, markdown, or tool names."
+ ),
+ },
+ ]
+ data = await state.kobold_client.chat(repair_messages, [])
+ choices = data.get("choices") or [{}]
+ choice = choices[0] or {}
+ message = choice.get("message") or {}
+ repaired = str(message.get("content") or "").strip()
+ if _looks_like_pseudo_tool_content(repaired):
+ return "I understand the matter, but I will not move until the terms are made plain."
+ return repaired
+
+
+DASHBOARD_HTML = """
+
+
+
+
+
+ LocalDiplomacy Agent
+
+
+
+
+ LocalDiplomacy Agent
+ Loading...
+
+
+
+
+ Status
+
+
Agent...
+
KoboldCpp...
+
Memory...
+
Last latency...
+
+
+