Add self-hosted AI worker bootstrap

2026-05-24 03:44:23 +00:00
parent 6d7cc534c4
commit a7c50f651a
6 changed files with 276 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Local AI Agent Guardrails
+
+These rules apply to any self-hosted AI coding assistant working on Agrarian.
+
+## Mandatory Behavior
+
+- Inspect existing project patterns before proposing changes.
+- Classify every task as `low`, `medium`, or `high` risk.
+- State evidence checked: files, docs, commands, logs, and build results.
+- Make the smallest useful change.
+- Do not refactor unrelated code.
+- Do not invent APIs or project conventions.
+- Do not merge directly to `main`.
+- Do not store secrets, private keys, wallet keys, passwords, or tokens in the
+  repo.
+- Passing tests/builds matter more than finishing the task.
+
+## Stop And Escalate
+
+Stop local work and prepare a Codex handoff when any of these are true:
+
+- confidence is below `0.65`,
+- tests fail twice,
+- build fails twice,
+- Unreal compile errors persist after one focused fix,
+- the task touches security, auth, payments, AGR wallet integration, save/load,
+  multiplayer, marketplace logic, migrations, or core engine architecture,
+- the diff touches more files than the brief allows,
+- local model context is overloaded,
+- the model cannot point to evidence for its recommendation.
+
+## Required Handoff Format
+
+```text
+Project:
+Branch:
+Goal:
+Risk:
+Confidence:
+Files inspected:
+Files changed:
+Commands run:
+Errors:
+What local AI tried:
+Why local AI stopped:
+Requested Codex action:
+```
+
+## Quality Bar
+
+Local AI is useful only when it is disciplined. It should be allowed to be
+uncertain, but it should not be allowed to be vague, overconfident, or
+unverified.
@@ -0,0 +1,74 @@
+# Agrarian Self-Hosted AI Development Stack
+
+This stack is meant to reduce pressure on Codex over time, not replace it
+immediately. The first production target is supervised local assistance:
+repository awareness, documentation, small safe edits, tests/builds, and clear
+Codex escalation when local tooling is over its head.
+
+## Current Services
+
+- Gitea:
+  `http://192.168.5.21:3000/nathan/agrarian-game.git`
+- Ollama:
+  `http://192.168.5.23:11434`
+- Open WebUI:
+  `http://192.168.5.26:8085`
+- Local AI worker VM:
+  `LinaAI / 192.168.5.27`
+- Primary Unreal/Linux development VM:
+  `unreal-engine / 192.168.5.20`
+
+## Current Local Model
+
+- `qwen2.5-coder:7b`
+- Role:
+  repo summaries, documentation, small patch suggestions, test generation,
+  straightforward scripts, and structured handoff preparation.
+- Not the role:
+  broad Unreal architecture changes, risky save/multiplayer/economy rewrites,
+  security-sensitive code, or autonomous merges.
+
+## Operating Model
+
+1. Local AI gathers context and proposes small changes.
+2. Work happens on a branch, not directly on `main`.
+3. The agent reports risk, files inspected, commands run, and confidence.
+4. Tests/builds decide whether a change is acceptable.
+5. After two failed local attempts, stop and escalate.
+6. Codex escalation uses the npm Codex CLI, not the API.
+7. Human review controls merges.
+
+## Codex Escalation
+
+Use `Scripts/ai_codex_escalate.sh` with a completed task status file. The
+script prefers a locally installed `codex` command and falls back to
+`npx -y @openai/codex exec`.
+
+Codex should be called for:
+
+- confidence below `0.65`,
+- two failed build/test attempts,
+- Unreal compile errors that persist,
+- tasks touching save systems, multiplayer, auth, payments, AGR wallet
+  integration, marketplace logic, migrations, or core architecture,
+- patches that grow beyond the intended small scope,
+- contradictions between local model output and official/project docs.
+
+## VM Boundaries
+
+- `LinaAI` owns local AI coding tools, Aider, Codex CLI escalation wrappers,
+  repo indexing, documentation generation, and small supervised branch work.
+- `unreal-engine` owns Unreal Engine source, editor builds, commandlets, and
+  game compile/package verification.
+- Keep these roles separated so AI tooling experiments do not destabilize the
+  Unreal build host.
+
+## Immediate Next Work
+
+- Verify Open WebUI model selection uses the Ollama backend at
+  `http://192.168.5.23:11434`.
+- Use Aider from `LinaAI`, not from `unreal-engine`.
+- Build project memory inside this repo under `Docs/` rather than creating a
+  separate documentation repository.
+- Add small local-agent tasks first: summarize systems, write docs, generate
+  tests, inspect logs, and prepare Codex handoffs.
@@ -14,6 +14,56 @@
 - The old `/home/nathan/agrarian/dev/ROADMAP.md` is coin/wallet-specific and
  should not be treated as the game roadmap.

+## Self-Hosted AI Development Stack Bootstrap - 2026-05-23
+
+- Nathan is starting a self-hosted AI build to reduce pressure on Codex while
+  keeping Codex as escalation through the npm Codex CLI rather than API usage.
+- Current service inventory:
+  - Gitea: `http://192.168.5.21:3000`
+  - Ollama: `http://192.168.5.23:11434`
+  - Open WebUI: `http://192.168.5.26:8085`
+  - local AI worker VM: `LinaAI / 192.168.5.27`
+  - primary Unreal build VM: `unreal-engine / 192.168.5.20`
+- Hardware observed:
+  - Unraid host: 12 CPU threads, 46 GiB RAM.
+  - `unreal-engine` VM: 8 CPU threads, 31 GiB RAM.
+  - local Codex shell host: 4 CPU threads, 3.7 GiB RAM.
+- Ollama model currently available:
+  `qwen2.5-coder:7b`.
+- Verified from `unreal-engine`:
+  Ollama chat API responded successfully with `local ai ready`.
+- Open WebUI is reachable, but the container template currently shows
+  `OLLAMA_BASE_URL=http://localhost:11434`; corrected the running container and
+  Unraid template to use `http://192.168.5.23:11434` and port `8085`.
+- Created `LinaAI` on Unraid:
+  - 4 vCPU,
+  - 12 GiB RAM,
+  - 100 GiB disk,
+  - static IP `192.168.5.27`,
+  - user `nathan`,
+  - passwordless sudo for MVP operations,
+  - autostart enabled.
+- Reduced `unreal-engine` persistent next-boot allocation to 6 vCPU / 24 GiB
+  RAM so LinaAI and the Unreal build VM can coexist. The running Unreal VM was
+  not hot-resized.
+- Cleaned the interrupted Aider install from `unreal-engine`; local AI tooling
+  belongs on `LinaAI`.
+- Installed on `LinaAI`:
+  - `aider-chat` via `pipx`,
+  - npm `@openai/codex`,
+  - Gitea clone at `/home/nathan/repos/AgrarianGame`.
+- Added self-hosted AI project documentation:
+  - `Docs/AI/SelfHostedAiDevelopmentStack.md`
+  - `Docs/AI/LocalAgentGuardrails.md`
+- Added initial supervised-agent scripts:
+  - `Scripts/ai_check_stack.sh`
+  - `Scripts/ai_task_status_template.json`
+  - `Scripts/ai_codex_escalate.sh`
+- Guardrail:
+  this is a supervised local-agent lane. No autonomous merges to `main`; local
+  AI prepares small changes, status files, verification results, and Codex
+  handoffs when confidence/build/test gates fail.
+
 ## AGR Wallet Integration Roadmap Update - 2026-05-21

 - Nathan clarified that AGR coin is a major investor hook for Agrarian: