forbocai 0.4.4 → 0.6.0

package/README.md

@@ -4,490 +4,37 @@
   
   <br/>
 
-# ForbocAI SDK
+# ForbocAI
+### `Légacy_Déporecation // Prótocol_Update`
 
-`Systém_Óverview // Prótocol_Init`
+**ᚠ ᛫ ᛟ ᛫ ᚲ**
 
-**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**
-
-Autonomous AI for game NPCs.
-
-[![Documentation](https://img.shields.io/badge/docs-docs.forboc.ai-blue)](https://docs.forboc.ai)
-[![npm](https://img.shields.io/npm/v/forbocai)](https://www.npmjs.com/package/forbocai)
-[![Discord](https://img.shields.io/discord/your-discord-id?label=Discord)](https://discord.gg/6hr2jHqnsG)
-
-</div>
-
-> *W̶e̴ ̶b̶u̷i̸l̶d̶ ̵t̵h̶e̴ ̷v̴e̴s̶s̷e̵l̴s̴.̷ ̷T̷h̵e̷y̸ ̴b̵r̴e̴a̷t̸h̸e̷ ̸t̴h̸e̶i̶r̶ ̴o̵w̷n̴ ̸l̸i̷f̷e̸.̸*
+The `forbocai` package has been ascended into a modularized monorepo. This package is now a **transparent proxy** for `@forbocai/core`.
 
 ---
 
-## 🚀 Publishing to NPM (Quick Reference)
-
-`Públish_Séquence // NPM_Deploý`
-
-To publish a new version to NPM:
+### `Instáll_Séquence // Pácкage`
 
+For universal protocol logic, state management, and soul portability:
 ```bash
-# 1. Bump version
-npm version <major|minor|patch> --no-git-tag-version
-
-# 2. Build
-npm run build
-
-# 3. Publish (use token from classified/AUTH.md)
-echo "//registry.npmjs.org/:_authToken=<TOKEN_FROM_CLASSIFIED_AUTH_MD>" > .npmrc
-npm publish --access public
-
-# 4. Clean up (IMPORTANT: don't commit .npmrc)
-rm .npmrc
-
-# 5. Commit and push
-git add . && git commit -m "chore: release vX.X.X" && git push
+npm install @forbocai/core
 ```
 
-> **Token Location**: The NPM token is stored in `../Forboc.AI/classified/AUTH.md`  
-> **Current Version**: Check `package.json` for the current version
-
----
-
-## Overview
-
-`Córe_Módules // SDK_Init`
-
-The **ForbocAI SDK** is an **Engine-Agnostic** toolkit for creating autonomous AI-powered NPCs in any game or application. **Node.js only** - browser support has been removed.
-
-- **Local SLM Cortex** — Run quantized Small Language Models (SLMs) natively via **node-llama-cpp**.
-- **Autonomous NPCs** — Create agents with persona, memory, and validated actions.
-- **Persistent Memory** — Local vector storage (LanceDB) for semantic recall.
-- **Portable Souls** — Permanent storage (Arweave) + Solana NFTs for tradeable agent identities.
-- **Automated QA** — Ghost Agents for headless testing at scale.
-- **API-Only Operation** — SDK requires API connectivity; no offline fallback strategies.
-
-**Requirements**:
-- **Node.js 18+** (Desktop/Server environments only)
-- **API Connectivity** — SDK requires connection to ForbocAI API for all operations
-- **CMake + C++ Build Tools** — Required for native Cortex module (`node-llama-cpp`)
-
----
-
-## 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.*
-
-**᛭ ᛫ ᛬ ᛫ ᛭**
-
----
-
-## Installation
-
-`Instáll_Séquence // Pácкage`
-
+For Node.js environments (SLM + Local Memory):
 ```bash
-# JavaScript/TypeScript
-npm install forbocai
+npm install @forbocai/node
 ```
 
-**Windows:** The SDK requires **CMake** and the **Visual Studio C++ workload** ("Desktop development with C++") to build the native Cortex (`node-llama-cpp`). The install runs a preinstall check; if it fails, you'll see a message for either missing CMake or missing C++ toolset. Install [CMake](https://cmake.org/download/) (add to PATH) and [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++" selected via the Visual Studio Installer (Modify → check "Desktop development with C++"). Then run `npm install forbocai` again.
-
----
-
-## CLI Reference
-
-`CLI_Tóols // Cómmand_Líne`
-
-The SDK includes a comprehensive CLI for managing your AI infrastructure.
-
+For browser environments (WebLLM + In-browser Memory):
 ```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://docs.forboc.ai/docs/pages/cli).
-
----
-
-## Quick Start
-
-`Quíck_Stárt // Éxample`
-
-```typescript
-import { createCortex, createAgent } from 'forbocai';
-
-// Córtex_Init // Loćal_Inférence
-const cortex = await createCortex({ model: 'smollm2-135m' });
-
-// Agént_Créate // NPC_Entíty
-const npc = await createAgent({
-  cortex,
-  persona: 'A suspicious merchant who was once cheated by adventurers.',
-  state: { inventory: ['rusty_key', 'healing_potion'], mood: 'suspicious' }
-});
-
-// Prócéss_Ínput // Dïalógue
-const response = await npc.process({
-  input: 'I want to buy a healing potion.',
-  context: { playerGold: 50 }
-});
-
-console.log(response.dialogue);
-// "Hmm, you have the coin... but how do I know you won't just take it and run?"
+npm install @forbocai/browser
 ```
-<!-- 0̶x̷E̷R̴R̵:̴ ̴I̴N̴F̵E̸C̶T̷I̵O̷N̷_̸D̶E̴T̷E̶C̸T̸E̶D̴ -->
 
 ---
 
-## Core Modules
-
-`Módulátion_Máp // Sýstem_Óverview`
-
-| Module | Description | Status |
-|--------|-------------|--------|
-| **Cortex** | Local SLM inference engine (Self-Contained) | ✅ Node (Native) / 🚧 C++ (UE) |
-| **Agent** | Autonomous entities with persona, state, memory | ✅ Complete |
-| **Memory** | Local Vector DB (IndexedDB / FS) | ✅ Complete |
-| **Bridge** | Neuro-symbolic action validation | ✅ Complete |
-| **Soul** | Portable agent state on Arweave/Solana | ✅ Complete |
-| **Ghost** | Headless QA testing at scale | ✅ Complete |
-
----
-
-## Architecture Overview
-
-`Systém_Architécture // Round_Tríp`
-
-The **ForbocAI SDK** orchestrates a **7-Step Round-Trip** between the Game, the Local Infrastructure, and the Cloud Mind.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      YOUR APPLICATION                       │
-├─────────────────────────────────────────────────────────────┤
-│   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
-│   │    Agent     │   │    Memory    │   │    Bridge    │    │
-│   └──────┬───────┘   └──────────────┘   └──────────────┘    │
-│          │ (1) Request                                      │
-│          ▼                                                  │
-│   ┌──────────────┐                                          │
-│   │   SDK Core   │ <────── (7) Execute ─────────────────┐   │
-│   └──────┬───────┘                                      │   │
-│          │ (2) Bundle                  (6) Verdict      │   │
-│          ▼                             (Signed)         │   │
-│   ┌──────────────┐  (3) Directive      ┌──────────────┐ │   │
-│   │  Cloud API   │ ──────────────────► │  Cloud API   │ │   │
-│   │  (The Law)   │                     │ (Validation) │ │   │
-│   └──────────────┘                     └──────▲───────┘ │   │
-│                                               │         │   │
-│          (4) Input                            │ (5)     │   │
-│          ▼                                    │ Submit  │   │
-│   ┌──────────────┐                            │         │   │
-│   │    Cortex    │ ───────────────────────────┘         │   │
-│   │  (SLM/LLM)   │      Generation                      │   │
-│   └──────────────┘                                      │   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**The Loop:**
-1.  **Game -> SDK**: Request Action.
-2.  **SDK -> API**: Send State/Memory.
-3.  **API -> SDK**: Return **Directive** (The Law).
-4.  **SDK -> Cortex**: Generate creative content based on Directive.
-5.  **SDK -> API**: Submit content for validation.
-6.  **API -> SDK**: Return **Verdict** (Signed Action).
-7.  **SDK -> Game**: Execute final action.
-
-*Note: For Enterprise usage, Step 4 can be replaced by a Cloud LLM provider, unifying the architecture for low-end (SLM) and high-end (LLM) devices.*
-
-
-`Mémory_Módule // Sémantic_Récall`
-
-The Memory module provides **privacy-first** local vector storage with semantic search.
-
-```typescript
-import { createMemory } from 'forbocai';
-
-// Initialize memory with temporal decay
-const memory = createMemory({
-  decay: 'temporal',        // Old memories fade over time
-  maxContextWindow: 10,     // Max memories per recall
-  storageKey: 'npc_memory'  // localStorage key
-});
-
-// Store observations with importance
-await memory.store('Player saved my life in battle', 'experience', 0.95);
-await memory.store('Found gold hidden in ruins', 'observation', 0.6);
-
-// Semantic recall (ranked by relevance × importance)
-const related = await memory.recall('Do I trust the player?', 5);
-// Returns memories about player saving life (high relevance)
-
-// Export for Soul portability
-const allMemories = memory.export();
-```
-
-**Features:**
-- **Local Storage**: All data stays in `localStorage` (browser) or memory (Node)
-- **Semantic Search**: Word overlap similarity (upgradeable to embeddings)
-- **Temporal Decay**: Older memories become less important over time
-- **API Sync**: Optional cloud backup via ForbocAI API
-
----
-
-## Module: Bridge (Action Validation)
-
-`Brídge_Módule // Néuro_Symbólic`
-
-The Bridge ensures AI-generated actions are **always valid** within game rules.
-
-```typescript
-import { createBridge, ValidationRule } from 'forbocai';
-
-const bridge = createBridge({
-  strictMode: true  // Reject unknown action types
-});
-
-// Validate an AI action
-const result = await bridge.validate(
-  { type: 'ATTACK', target: 'orc_1' },
-  {
-    agentState: { hp: 85, mana: 50 },
-    worldState: { entities: ['orc_1', 'player_1'] }
-  }
-);
-
-if (result.valid) {
-  executeAction(result.correctedAction || action);
-} else {
-  console.log('Invalid action:', result.reason);
-  // Falls back to IDLE
-}
-
-// Register custom rules
-bridge.registerRule({
-  id: 'game.fly',
-  name: 'Flying Validation',
-  actionTypes: ['FLY'],
-  validate: (action, ctx) => {
-    const hasWings = ctx.agentState?.hasWings;
-    return hasWings 
-      ? { valid: true }
-      : { valid: false, reason: 'Agent cannot fly without wings' };
-  }
-});
-```
-
-**Built-in Rules:**
-- `core.movement` — Validates MOVE coordinates and world bounds
-- `core.attack` — Validates ATTACK target exists
-- `core.interact` — Validates INTERACT object specified
-- `core.speak` — Validates SPEAK text not empty
-- `core.resources` — Validates HP/mana sufficient for action
-
----
-
-## Module: Soul (Portable Agent Identity)
-
-`Sóul_Módule // Pórtal_Idéntity`
-
-The Soul module enables **cross-game agent portability** via permanent storage (Arweave) and Solana NFTs.
-
-```typescript
-import { createSoulInstance, importSoulFromUri } from 'forbocai';
-
-// Create a Soul from agent data
-const soul = createSoulInstance(
-  'agent_123',
-  'Kira the Merchant',
-  'A suspicious merchant who distrusts adventurers',
-  { mood: 'suspicious', inventory: ['rusty_key'] },
-  memories  // From Memory module
-);
-
-// Export to Arweave (permanent, pay-once storage)
-const { cid, uri, signature } = await soul.export();
-console.log(`Soul stored: ${uri}`);
-
-// Import Soul in another game
-const importedSoul = await importSoulFromUri(cid);
-console.log(importedSoul.persona);
-// "A suspicious merchant who distrusts adventurers"
-
-// Create new agent from Soul
-import { createAgentFromSoul } from 'forbocai';
-const { agentId, persona } = await createAgentFromSoul(cid, cortexId);
-```
-
-**Features:**
-- **Arweave Storage**: Permanent, pay-once (no pinning fees)
-- **Encryption**: Soul content encrypted; key transfers with NFT ownership
-- **NFT-Ready**: Metaplex Core on Solana for tradeable agent identities
-
----
-
-## Module: Ghost (Automated QA)
-
-`Ghóst_Módule // Autómated_QA`
-
-The Ghost module runs **headless AI agents** for automated game testing.
-
-```typescript
-import { createGhost } from 'forbocai';
-
-// Configure Ghost session
-const ghost = createGhost({
-  testSuite: 'exploration',  // or 'combat', 'dialogue', 'pathfinding', 'full'
-  duration: 300,             // seconds
-  captureScreenshots: true
-});
-
-// Start session
-const sessionId = await ghost.run();
-console.log(`Ghost session started: ${sessionId}`);
-
-// Poll status
-const status = await ghost.status();
-console.log(`Progress: ${status.progress}%`);
-
-// Wait for completion with progress callback
-const results = await ghost.waitForCompletion(
-  5000,   // Poll every 5 seconds
-  300000, // Timeout after 5 minutes
-  (status) => console.log(`${status.progress}% complete`)
-);
-
-// Analyze results
-console.log(`Tests: ${results.passed}/${results.totalTests} passed`);
-console.log(`Coverage: ${(results.coverage * 100).toFixed(1)}%`);
-console.log(`Avg FPS: ${results.metrics.avgFrameRate}`);
-
-// View failed tests
-results.tests
-  .filter(t => !t.passed)
-  .forEach(t => console.log(`FAIL: ${t.name} - ${t.error}`));
-```
-
-**Test Suites:**
-- `exploration` — Pathfinding, map coverage, navigation
-- `combat` — Battle mechanics, AI decisions, balance
-- `dialogue` — NPC conversations, branching logic
-- `pathfinding` — Navigation mesh, obstacle avoidance
-- `full` — All tests combined
-
-**Metrics Collected:**
-- `avgFrameRate` — Average FPS during test
-- `memoryUsageMB` — Peak memory usage
-- `aiDecisionsPerSec` — Agent decision throughput
-- `explorationCoverage` — Map area discovered
-
-
-
-## Digital Souls (Solana/Metaplex)
-
-`Assét_Cláss // The_Sóul`
-
-In the ForbocAI ecosystem, an NFT is not just a receipt—it is an **Encapsulated Soul**.
-
-*   **The Container**: A standardized bundle containing the Agent's Personality, Memories, and State.
-*   **The Chain**: The NFT is the *Deed of Ownership* pointing to this digital life.
-*   **Portability**: Take your trained NPC from *Forboc* to a sequel or entirely different world. Uses Arweave for permanent, pay-once storage.
-*   **Economy**: Train a specialist NPC and sell it on the open market. The value is in the *Experience*, not just the skin.
-
-<!-- T̵h̷e̶ ̷s̸o̷u̷l̴ ̶i̶s̵ ̶n̵o̸t̵ ̵f̸o̵r̶ ̵s̷a̸l̶e̷.̶ ̴I̸t̸ ̴i̵s̷ ̶l̶e̷a̵s̵e̶d̴.̷ -->
-
----
-
-## Documentation
-
-`Dócs_Máp // Référence`
-
-- **[Introduction](https://docs.forboc.ai)** — SDK overview and quick start
-- **[User Stories](https://docs.forboc.ai/user-stories)** — BDD specifications for all features
-- **[Concepts](https://docs.forboc.ai/concepts)** — Architecture and core abstractions
-- **[API Reference](https://docs.forboc.ai/api-reference)** — Complete endpoint documentation
-
----
-
-## Links
-
-`Éxternal_Líns // Cónnect`
-
-- **Website:** [forboc.ai](https://forboc.ai)
-- **Documentation:** [docs.forboc.ai](https://docs.forboc.ai)
-- **Discord:** [discord.gg/6hr2jHqnsG](https://discord.gg/6hr2jHqnsG)
-- **Telegram:** [t.me/forbocai](https://t.me/forbocai)
-
----
-
-**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**
- 
- ## Developers
- 
- `Dev_Ops // Releáse_Cycles`
- 
- To redeploy the SDK to NPM:
- 
- 1.  **Bump Version**: Update `version` in `package.json`.
- 2.  **Build**: `npm run build` (Generates `dist/`).
- 3.  **Auth**: Ensure `sdk/.npmrc` contains the valid token from `../api/NPM_TOKEN.md`.
-     ```bash
-     # Command to configure local .npmrc
-     echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN_HERE" > .npmrc
-     ```
- 4.  **Publish**: `npm publish --access public`.
- 
- > **Note**: The `.npmrc` file is gitignored (`.gitignore`) to prevent leaking secrets. Always verify the token in `api/NPM_TOKEN.md` matches the active Granular Access Token.
-
-## 🧪 Testing Flow
-
-`Tést_Séquence // Válidátion`
-
-To verify the full end-to-end loop (SDK <-> NPM <-> Render API):
-
-1.  **Local Updates**: Make changes to `sdk/` or `api/` code.
-2.  **Deploy**:
-    *   **SDK**: Push to NPM (see [Developers](#developers) section above).
-    *   **API**: Commit and push changes to GitHub (triggers Render auto-deploy).
-3.  **Consume**:
-    ```bash
-    # In your client app (e.g. Forboc/client)
-    npm install forbocai@latest
-    ```
-4.  **Verify**:
-    Use the CLI to check connection to the production API:
-    ```bash
-    npx forbocai api status
-    # > Checking API Status (https://api.forboc.ai)...
-    # > Status: ONLINE
-    ```
-
-
-## License
+> *Logic must be pure. Order must be absolute.*
 
-`Légal_Státus // Ríghts`
+**᛭ ᛫ ᛬ ᛫ ᛭**
 
-All rights reserved. © 2026 ForbocAI. See [LICENSE](./LICENSE) for full details.
-## 🌑 Aesthetic Protocols
-See [style-guide.md](./style-guide.md) for mandatory grimdark cyberpunk noir aesthetic standards (Runes, Zalgo, ASCII).
-<!-- T̸h̴e̶ ̶v̶o̶i̶d̴ ̷c̸o̶n̷s̶u̶m̸e̸s̶ ̸a̶l̷l̵. -->
+Documentation: [docs.forboc.ai](https://docs.forboc.ai)  
+Website: [forboc.ai](https://forboc.ai)

package/index.d.ts

@@ -0,0 +1,2 @@
+// Transparent TypeScript proxy to @forbocai/core
+export * from '@forbocai/core';

package/index.js

@@ -0,0 +1,2 @@
+// Transparent proxy to @forbocai/core
+module.exports = require('@forbocai/core');

package/package.json

@@ -1,48 +1,22 @@
 {
   "name": "forbocai",
-  "version": "0.4.4",
+  "version": "0.6.0",
+  "description": "The Infrastructure Layer for Digital Souls (Legacy Redirect)",
+  "main": "index.js",
+  "types": "index.d.ts",
   "license": "UNLICENSED",
-  "description": "The Infrastructure Layer for Autonomous AI Characters",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "forbocai": "dist/cli.js"
+  "author": "seandinwiddie <sean@forboc.ai>",
+  "homepage": "https://forboc.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ForbocAI/sdk.git",
+    "directory": "packages/legacy"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --watch",
-    "test": "vitest",
-    "test:watch": "vitest --watch",
-    "preinstall": "node scripts/check-cmake.js",
-    "postinstall": "node postinstall.js",
-    "sync-version": "node -e \"const v=require('./package.json').version; const f=require('fs'); const p='src/index.ts'; let s=f.readFileSync(p,'utf8'); s=s.replace(/SDK_VERSION = '[^']+'/,'SDK_VERSION = \\''+v+'\\''); f.writeFileSync(p,s);\""
+    "build": "echo 'Nothing to build for legacy'"
   },
   "dependencies": {
-    "@irys/sdk": "^0.1.1",
-    "@lancedb/lancedb": "^0.23.0",
-    "@xenova/transformers": "^2.17.2",
-    "apache-arrow": "^18.1.0",
-    "axios": "^1.6.2",
-    "node-llama-cpp": "^3.15.1",
-    "onnxruntime-node": "^1.23.2",
-    "zod": "^3.22.4"
+    "@forbocai/core": "^0.6.0"
   },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^1.0.0"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "package.json",
-    "postinstall.js",
-    "scripts"
-  ],
-  "overrides": {
-    "glob": "^11.0.0",
-    "rimraf": "^5.0.0"
-  }
+  "deprecated": "This package is now a transparent proxy for @forbocai/core. Please migrate to the core package directly."
 }

package/LICENSE

@@ -1,7 +0,0 @@
-Copyright (c) 2026 ForbocAI, Inc. All Rights Reserved.
-
-Proprietary and Confidential.
-
-This software and all related documentation are the sole property of ForbocAI, Inc. 
-Unauthorized copying, modification, distribution, or any other use of this 
-software, via any medium, is strictly prohibited.