From 87bfcbd5bd37440c6f516c569cf025c5ccabc7c7 Mon Sep 17 00:00:00 2001 From: Me Date: Tue, 26 May 2026 00:29:57 -0700 Subject: [PATCH] yippie --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2aeac4f --- /dev/null +++ b/README.md @@ -0,0 +1,135 @@ +# SmarterAgents: Autonomous Multi-Agent Orchestration Framework + +An elite, production-grade local AI agent framework designed for unified memory architectures, specifically optimized for the **AMD Framework 16 Laptop (Ryzen 9 7940HS / Radeon 780M iGPU / GFX1103)** running accelerated inference via the Mesa Vulkan `RADV` driver on Fedora Linux. + +This framework abandons monolithic agent loops in favor of a **Decoupled Model Context Protocol (MCP)** architecture. It utilizes a single, resident 14B-class LLM, dynamically toggling its cognitive reasoning state to orchestrate a multi-persona pipeline (Planner $\rightarrow$ Builder $\rightarrow$ Reviewer). All local state, execution failures, and design variables are actively vectorized into a localized CPU-bound RAG pipeline for low-latency, self-healing execution. + +--- + +## 1. System Architecture & Directory Layout + +The environment strictly separates the transport broker layer from tool execution and active agent sandboxes. No automated agents write to the `core/` or `dev/` directories. + +```text +. +├── agents # Immutable agent configuration profiles, tools, and dynamic spaces +│ ├── default_agent.md +│ ├── modules +│ │ └── geoscaper # Low-level workspace tool logic invoked by MCP server +│ ├── tools +│ │ └── tool_rules.gbnf # Strict structural logit constraints for Builder turns +│ └── workspaces/ # Isolated Agent Sandbox Environment +│ └── MMDDprojectname_workspace/ # Dynamic task-specific runtime directory +│ ├── 00cache.json # Global design vectors, tokens, and active styles +│ ├── 00memory_vault.db# In-process sqlite-vec engine (768-dim float array store) +│ ├── 00tasks.json # Project feature checklist and sequence goals [Fully Embedded] +│ ├── 00lessons_learned.md # Global closed-fault and successful repair ledger +│ ├── 01plan_handoff.md# Planner execution payload (Thinking: Enabled) +│ ├── 02build_handoff.md# Builder compilation summary payload +│ └── 03review_audit.md# Accumulative Audit Ledger [Append-Only Block Records] +├── core # Source logic and foundational runtime engines ONLY +│ ├── smarterframework.py # Transport broker (Discover, Constrain, Execute) +│ ├── llama.cpp # Core inference execution backend +│ ├── cache/ # System-level internal runtime engine caches +│ └── logs/ # Standard input/output framework system logs +├── dev # Strict User Space: Backups, manual synching, manual logs +│ ├── 00plan_v1.md +│ ├── 00scratch.txt +│ ├── agent_stream.log +│ ├── llama-server.log +│ └── staging +│ ├── 01CACHE +│ ├── 02OLD +│ └── 03PROTO +├── models # Binary Storage Tier +│ ├── Huihui-Qwen3-8B-abliterated-v2.i1-Q5_K_M.gguf +│ ├── Qwen3.5-4B-Q4_K_M.gguf +│ └── Qwen3-14B-Instruct-Abliterated-Q4_K_M.gguf +├── README.md +├── stage.sh +└── start.sh + +``` + +--- + +## 2. Core Operational Pipelines + +### The Decoupled Transport Broker (`smarterframework.py`) + +The Python orchestrator is entirely tool-agnostic. It does not parse code, resolve paths, or execute system commands directly. It strictly manages the MCP network cycle: + +1. **Discover:** Queries the MCP server for capabilities (`tools/list`). +2. **Constrain:** Maps schema parameters to local `GBNF` JSON grammars. +3. **Execute:** Forwards rigid argument values to the target tool (`tools/call`). + +### The Multi-Persona State Machine + +To prevent instruction leakage and context dilution, the orchestrator executes a hard wipe of the context window between every phase transition, toggling the model's cognitive mode natively: + +* **Phase 1: The Planner.** (`enable_thinking=True`). Outputs strategic architecture to `01plan_handoff.md`. +* **Phase 2: The Builder.** (`enable_thinking=False` + GBNF Constraint). Emits zero-latency JSON tool payloads to execute components. Outputs to `02build_handoff.md`. +* **Phase 3: The Reviewer.** (`enable_thinking=True`). Audits compiled outputs against `00tasks.json` constraints. Appends results to `03review_audit.md`. + +### Active Memory Pipeline (`MemoryVault`) + +All workspace iterations are systematically vectorized in-process. To preserve Vulkan execution lanes for the primary 14B model, the embedding pipeline runs entirely on the host CPU. + +* **Engine:** `sqlite-vec` + `nomic-embed-text-v1.5`. +* **Self-Healing Recovery:** If the Builder receives a non-zero exit code or the Reviewer logs a rejection block, the framework automatically extracts the error trace, executes a k-NN distance search against the `00memory_vault.db`, and spins up a fresh Builder instance pre-loaded with the top 3 historic fixes. + +--- + +## 3. Target Hardware Optimization + +This framework operates safely within a **32GB Shared Memory Ceiling** operating at 89.6 GB/s bandwidth. + +* **VRAM Allocation:** Up to ~9.5 GB allocated to the 14B Q4_K_M model matrix via Vulkan. +* **Context Cap Limit:** Context space is artificially restricted to `16384` (`--ctx-size 16384`) to prevent the KV Cache from exceeding ~4.4GB and causing out-of-memory kernel panics. +* **Unified Memory Safety:** Pre-allocates unified memory safely and prevents page table collisions by bypassing OS memory mapping (`--no-mmap`). +* **Physical Core Alignment:** Restricts processing to exactly `8` physical threads (`--threads 8`), eliminating SMT resource contention. +* **GPU Queue Splitting:** Batch processing is throttled (`--batch-size 128` and `--ubatch-size 64`) to prevent `amdgpu` driver timeouts (TDR). + +--- + +## 4. Setup & Compilation + +### Step 1: Install Python Dependencies + +The orchestrator requires specific libraries for runtime type guarding and the local vector engine: + +```bash +pip install pydantic sentence-transformers sqlite-vec numpy + +``` + +### Step 2: Compile the Vulkan Inference Engine + +Compile `llama-server` locally using the Mesa Vulkan driver stack, utilizing Link-Time Optimization (`LTO`) and `jemalloc`: + +```bash +cd core/llama.cpp +cmake -B build -DGGML_VULKAN=1 -DLLAMA_LTO=ON -DLLAMA_JEMALLOC=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS="-O3 -march=native -mtune=native" -DCMAKE_CXX_FLAGS="-O3 -march=native -mtune=native" +cmake --build build --config Release -j$(nproc) + +``` + +### Step 3: ELF Dynamic Linking Fix (One-Time Execution) + +To execute `llama-server` seamlessly from the root folder without dynamic linker errors, patch the binary to search its own directory for compiled shared objects: + +```bash +sudo dnf install patchelf +patchelf --set-rpath '$ORIGIN' ./core/llama.cpp/build/bin/llama-server + +``` + +### Step 4: Execute the Pipeline + +Run the unified start script from the root directory. This script initializes the Vulkan backend, performs memory health checks, boots the CPU-based `MemoryVault`, and triggers the asynchronous `smarterframework.py` orchestrator loop. + +```bash +chmod +x start.sh +./start.sh + +``` \ No newline at end of file