forbocai 0.2.0 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 <br/>
 <div align="center">
-  <img alt="ForbocAI logo" src="https://forbocai.github.io/logo.png" height="50" align="center">
+  <img alt="ForbocAI logo" src="https://forboc.ai/logo.png" height="50" align="center">
   
   <br/>
 
@@ -57,11 +57,34 @@ git add . && git commit -m "chore: release vX.X.X" && git push
 
 The **ForbocAI SDK** is an **Engine-Agnostic** toolkit for creating autonomous AI-powered NPCs in any game or application. It runs anywhere (Node, Browser, Python, Rust).
 
-- **Local SLM Cortex** — Run quantized Small Language Models in your environment
-- **Autonomous NPCs** — Create agents with persona, memory, and validated actions
-- **Persistent Memory** — RAG pipeline for semantic recall across sessions
-- **Portable Souls** — Export agent state to IPFS for cross-application use
-- **Automated QA** — Ghost Agents for headless testing at scale
+- **Local SLM Cortex** — Run **WebLLM** (SmolLM2, Llama3) directly in-browser via WebGPU.
+- **Autonomous NPCs** — Create agents with persona, memory, and validated actions.
+- **Persistent Memory** — **IndexedDB** vector storage for 10k+ memories.
+- **Portable Souls** — P2P **IPFS** pinning via integrated Helia node.
+- **Automated QA** — Ghost Agents for headless testing at scale.
+
+**Requirements**:
+- Browser with **WebGPU** support (Chrome 113+, Edge 113+) for Cortex.
+- Node.js 18+ for CLI/Build.
+
+---
+
+## Architectural Philosophy (Strict)
+
+`Code_Dóctrine // Pure_Fúnction`
+
+The ForbocAI SDK strictly adheres to **Functional Programming (FP)** principles to ensure predictable, testable, and robust AI behavior.
+
+### 🚫 The No-Class Manifesto
+We **reject** Object-Oriented Programming (OOP) classes (`class`) in favor of **Functional Composition**.
+- **State is Immutable**: Objects are never mutated in place. New versions are returned.
+- **Pure Functions**: Logic is separated from data. Functions receive input and return output with no side effects.
+- **Factory Pattern**: We use factory functions with **closures** to encapsulate private state (`createAgent`, `createMemory`) instead of classes (`new Agent`).
+
+### Why?
+AI state (memories, personality, mood) is complex and sensitive. Classes encourage hidden mutations that lead to "Ghost in the Machine" bugs. Pure functions ensure that every thought process is traceable and reproducible.
+
+> *Logic must be pure. Order must be absolute.*
 
 **᛭ ᛫ ᛬ ᛫ ᛭**
 
@@ -78,6 +101,31 @@ npm install forbocai
 
 ---
 
+## CLI Reference
+
+`CLI_Tóols // Cómmand_Líne`
+
+The SDK includes a comprehensive CLI for managing your AI infrastructure.
+
+```bash
+# Agents
+npx forbocai agent create "A wise wizard"
+npx forbocai agent list
+npx forbocai agent chat <agentId>
+
+# Memory & Bridge
+npx forbocai memory recall <agentId> "battle"
+npx forbocai bridge validate action.json
+
+# System
+npx forbocai status
+npx forbocai doctor
+```
+
+See [full CLI documentation](https://forbocai.docs.buildwithfern.com/docs/pages/cli).
+
+---
+
 ## Quick Start
 
 `Quíck_Stárt // Éxample`
@@ -114,16 +162,46 @@ console.log(response.dialogue);
 
 | Module | Description | Status |
 |--------|-------------|--------|
-| **Cortex** | Local SLM inference engine (Engine Agnostic) | ✅ Complete |
+| **Cortex** | Local SLM inference engine (Self-Contained) | ✅ Browser / 🚧 Node |
 | **Agent** | Autonomous entities with persona, state, memory | ✅ Complete |
-| **Memory** | RAG pipeline for persistent semantic recall | ✅ Complete |
+| **Memory** | Local Vector DB (IndexedDB / FS) | ✅ Complete |
 | **Bridge** | Neuro-symbolic action validation | ✅ Complete |
 | **Soul** | Portable agent state on IPFS/Solana | ✅ Complete |
 | **Ghost** | Headless QA testing at scale | ✅ Complete |
 
 ---
 
-## Module: Memory (Local Vector DB)
+## The Neural Grid
+
+`Systém_Architécture // Cónnection`
+
+The **ForbocAI Protocol** strictly separates **State** (SDK) from **Logic** (API).
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                         THE NEURAL GRID                        │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│   ┌──────────────┐          ┌──────────────┐                   │
+│   │     SDK      │          │     API      │                   │
+│   │ (Container)  │◄────────►│ (Pure Logic) │                   │
+│   └──────────────┘          └──────────────┘                   │
+│          │                          │                          │
+│     The VESSEL                  The TRUTH                      │
+│   [SLM + VectorDB]           [Stateless Rules]                 │
+│   [Memory + Soul]            [No Database]                     │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+1.  **SDK is the Body**: It contains the *entire* existence of the Agent.
+    *   **SLM Cortex**: The brain (Local Inference).
+    *   **Vector Memory**: The memory (Local Storage).
+    *   **Self-Contained**: Runs locally (Browser/Node/Python/Rust) without external dependencies.
+2.  **API is the Law**: It is a stateless oracle that validates reality.
+    *   **No Database**: The API never stores agent state.
+    *   **Pure Functions**: Input (Action) → Output (Validation).
+
 
 `Mémory_Módule // Sémantic_Récall`
 
@@ -306,38 +384,7 @@ results.tests
 - `aiDecisionsPerSec` — Agent decision throughput
 - `explorationCoverage` — Map area discovered
 
----
-
-## The Neural Grid
-
-`Systém_Architécture // Cónnection`
-
-The **ForbocAI Protocol** enables agents to understand the world they inhabit.
 
-```
-┌────────────────────────────────────────────────────────────────┐
-│                    THE NEURAL GRID                              │
-├────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│   ┌──────────────┐    ┌─────────────┐    ┌──────────────┐      │
-│   │    GAME      │    │     SDK     │    │     API      │      │
-│   │  (Execution) │◄──►│ (Container) │◄──►│   (Logic)    │      │
-│   └──────────────┘    └─────────────┘    └──────────────┘      │
-│         │                   │                   │               │
-│    World Brain          The Body            The Mind            │
-│    (Physics)         (SLM + VectorDB)    (Pure Functions)       │
-│                                                                 │
-└────────────────────────────────────────────────────────────────┘
-```
-
-1.  **Synthetic Intuition**: Agents "feel" the state of the world through standardized Observations.
-2.  **Valid Action**: Agents express their intent through standardized Actions, ensuring they never break the rules of physics.
-3.  **Engine Agnostic**: Whether in a text adventure or a 3D simulation, the Agent's soul remains consistent.
-
-This ensures that NPCs are **smart** (thanks to LLMs) but **reliable** (thanks to the Grid).
-> ⚠️ **W̸A̴R̷N̷I̷N̵G̸**: S̴y̸n̷t̶h̵e̷t̸i̵c̸ ̶I̵n̴t̷u̸i̷t̸i̶o̶n̴ ̶m̶a̵y̴ ̶c̴a̷u̸s̷e̶ ̷u̷n̷i̸n̵t̸e̵n̴d̶e̵d̵ ̸s̴e̸n̶t̵i̷e̷n̶c̴e̴.
-
----
 
 ## Digital Souls (Solana/Metaplex)
 
@@ -369,7 +416,7 @@ In the ForbocAI ecosystem, an NFT is not just a receipt—it is an **Encapsulate
 
 `Éxternal_Líns // Cónnect`
 
-- **Website:** [forbocai.github.io](https://forbocai.github.io)
+- **Website:** [forboc.ai](https://forboc.ai)
 - **Documentation:** [forbocai.docs.buildwithfern.com](https://forbocai.docs.buildwithfern.com)
 - **Discord:** [discord.gg/6hr2jHqnsG](https://discord.gg/6hr2jHqnsG)
 - **Telegram:** [t.me/forbocai](https://t.me/forbocai)