forbocai 0.0.7 → 0.0.8

package/README.md

@@ -13,10 +13,13 @@
 Autonomous AI for game NPCs.
 
 [![Documentation](https://img.shields.io/badge/docs-forbocai.docs.buildwithfern.com-blue)](https://forbocai.docs.buildwithfern.com)
+[![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̸.̸*
+
 ---
 
 ## Overview
@@ -42,12 +45,6 @@ The **ForbocAI SDK** is an **Engine-Agnostic** toolkit for creating autonomous A
 ```bash
 # JavaScript/TypeScript
 npm install forbocai
-
-# Python
-pip install forbocai
-
-# Rust
-cargo add forbocai
 ```
 
 ---
@@ -78,6 +75,7 @@ const response = await npc.process({
 console.log(response.dialogue);
 // "Hmm, you have the coin... but how do I know you won't just take it and run?"
 ```
+<!-- 0̶x̷E̷R̴R̵:̴ ̴I̴N̴F̵E̸C̶T̷I̵O̷N̷_̸D̶E̴T̷E̶C̸T̸E̶D̴ -->
 
 ---
 
@@ -103,10 +101,11 @@ console.log(response.dialogue);
 The **ForbocAI Protocol** enables agents to understand the world they inhabit.
 
 1.  **Synthetic Intuition**: Agents "feel" the state of the world through standardized Observations.
-2.  **Valid Action**: Agents express their intent through validated Actions, ensuring they never break the rules of physics.
+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̴.
 
 ---
 
@@ -121,6 +120,8 @@ In the ForbocAI ecosystem, an NFT is not just a receipt—it is an **Encapsulate
 *   **Portability**: Take your trained NPC from *Forboc* to a sequel or entirely different world. Uses IPFS for decentralized persistence.
 *   **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
@@ -164,4 +165,7 @@ In the ForbocAI ecosystem, an NFT is not just a receipt—it is an **Encapsulate
 
 `Légal_Státus // Ríghts`
 
-All rights reserved. © 2026 ForbocAI
+All rights reserved. © 2026 ForbocAI
+## 🌑 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̵. -->

package/dist/cli.js

@@ -29,7 +29,27 @@ var API_URL = "https://forbocai-api.onrender.com/status";
 var args = process.argv.slice(2);
 var command = args[0];
 var subcommand = args[1];
+var subcommand2 = args[2];
 if (command === "api" && subcommand === "status") {
+  checkApiStatus();
+} else if (command === "agent" && subcommand === "create") {
+  const persona = subcommand2 || "Default Persona";
+  console.log(`> Creating Agent with persona: "${persona}"...`);
+  console.log(`> [Mock] Agent created. ID: ag_${Math.floor(Math.random() * 1e3)}`);
+} else if (command === "soul") {
+  if (subcommand === "export") {
+    const agentId = subcommand2;
+    console.log(`> Exporting Soul for Agent: ${agentId}...`);
+    console.log(`> [Mock] Soul exported to IPFS. CID: Qmhash_${Math.random().toString(36).substring(7)}`);
+  } else if (subcommand === "import") {
+    const cid = subcommand2;
+    console.log(`> Importing Soul from CID: ${cid}...`);
+    console.log(`> [Mock] Agent rehydrated from Soul.`);
+  }
+} else {
+  printUsage();
+}
+function checkApiStatus() {
   console.log(`> Checking API Status (https://forbocai-api.onrender.com)...`);
   import_https.default.get(API_URL, (res) => {
     let data = "";
@@ -52,6 +72,11 @@ if (command === "api" && subcommand === "status") {
   }).on("error", (e) => {
     console.error(`> Error: ${e.message}`);
   });
-} else {
-  console.log("Usage: forbocai api status");
+}
+function printUsage() {
+  console.log("Usage:");
+  console.log("  forbocai api status");
+  console.log("  forbocai agent create <persona>");
+  console.log("  forbocai soul export <agentId>");
+  console.log("  forbocai soul import <cid>");
 }

package/dist/cli.mjs

@@ -6,7 +6,27 @@ var API_URL = "https://forbocai-api.onrender.com/status";
 var args = process.argv.slice(2);
 var command = args[0];
 var subcommand = args[1];
+var subcommand2 = args[2];
 if (command === "api" && subcommand === "status") {
+  checkApiStatus();
+} else if (command === "agent" && subcommand === "create") {
+  const persona = subcommand2 || "Default Persona";
+  console.log(`> Creating Agent with persona: "${persona}"...`);
+  console.log(`> [Mock] Agent created. ID: ag_${Math.floor(Math.random() * 1e3)}`);
+} else if (command === "soul") {
+  if (subcommand === "export") {
+    const agentId = subcommand2;
+    console.log(`> Exporting Soul for Agent: ${agentId}...`);
+    console.log(`> [Mock] Soul exported to IPFS. CID: Qmhash_${Math.random().toString(36).substring(7)}`);
+  } else if (subcommand === "import") {
+    const cid = subcommand2;
+    console.log(`> Importing Soul from CID: ${cid}...`);
+    console.log(`> [Mock] Agent rehydrated from Soul.`);
+  }
+} else {
+  printUsage();
+}
+function checkApiStatus() {
   console.log(`> Checking API Status (https://forbocai-api.onrender.com)...`);
   https.get(API_URL, (res) => {
     let data = "";
@@ -29,6 +49,11 @@ if (command === "api" && subcommand === "status") {
   }).on("error", (e) => {
     console.error(`> Error: ${e.message}`);
   });
-} else {
-  console.log("Usage: forbocai api status");
+}
+function printUsage() {
+  console.log("Usage:");
+  console.log("  forbocai api status");
+  console.log("  forbocai agent create <persona>");
+  console.log("  forbocai soul export <agentId>");
+  console.log("  forbocai soul import <cid>");
 }

package/dist/index.d.mts

@@ -9,6 +9,9 @@ interface CortexConfig {
     temperature?: number;
     maxTokens?: number;
     gpu?: boolean;
+    /** Connection Config */
+    authKey?: string;
+    apiUrl?: string;
 }
 interface CortexStatus {
     id: string;
@@ -22,12 +25,6 @@ interface CompletionOptions {
     stop?: string[];
     jsonSchema?: object;
 }
-interface Cortex {
-    id: string;
-    init(): Promise<void>;
-    complete(prompt: string, options?: CompletionOptions): Promise<string>;
-    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
-}
 type Mood = 'hostile' | 'suspicious' | 'neutral' | 'friendly' | 'loyal';
 interface AgentState {
     inventory: string[];
@@ -37,22 +34,17 @@ interface AgentState {
     [key: string]: unknown;
 }
 interface AgentConfig {
-    cortex: Cortex;
+    cortex: any;
     persona: string;
     initialState?: Partial<AgentState>;
     memoryConfig?: MemoryConfig;
+    apiUrl?: string;
 }
 interface AgentResponse {
     dialogue: string;
     action?: AgentAction;
     thought?: string;
 }
-interface AgentAction {
-    type: string;
-    target?: string;
-    payload?: Record<string, unknown>;
-    reason?: string;
-}
 type MemoryType = 'observation' | 'experience' | 'knowledge' | 'emotion';
 interface MemoryConfig {
     /** Decay strategy: 'none' | 'temporal' */
@@ -68,6 +60,28 @@ interface MemoryItem {
     type: MemoryType;
     importance: number;
 }
+interface Observation {
+    type: 'event' | 'state' | 'request';
+    timestamp: number;
+    agentId?: string;
+    gameId?: string;
+    data: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+interface Directive {
+    type: 'system-prompt' | 'action-constraints' | 'behavior-rules';
+    content: string;
+    constraints?: Record<string, unknown>;
+    priority?: 'high' | 'normal' | 'low';
+    expiresAt?: number;
+}
+interface AgentAction {
+    type: string;
+    target?: string;
+    payload?: Record<string, unknown>;
+    reason?: string;
+    confidence?: number;
+}
 interface Soul {
     id: string;
     version: string;
@@ -78,11 +92,90 @@ interface Soul {
     signature?: string;
 }
 
+/**
+ * Interface for Cortex inference engine
+ */
+interface ICortex {
+    init(): Promise<CortexStatus>;
+    complete(prompt: string, options?: CompletionOptions): Promise<string>;
+    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
+    processObservation(observation: Observation): Promise<Directive>;
+    generateAction(directive: Directive): Promise<AgentAction>;
+}
+/**
+ * Cortex factory function - creates a new Cortex instance
+ */
+declare const createCortex: (config: CortexConfig) => ICortex;
+/**
+ * Pure function to generate completion text
+ * Deterministic output for same input (functional principle)
+ */
+declare const generateCompletion: (prompt: string, options: CompletionOptions, modelId: string) => string;
+/**
+ * Pure function to process observation and return directive
+ */
+declare const processObservationToDirective: (observation: Observation) => Directive;
+/**
+ * Pure function to generate action from directive
+ */
+declare const generateActionFromDirective: (directive: Directive) => AgentAction;
+/**
+ * Mock Cortex for testing
+ */
+declare class MockCortex implements ICortex {
+    init(): Promise<CortexStatus>;
+    complete(prompt: string): Promise<string>;
+    completeStream(prompt: string): AsyncGenerator<string>;
+    processObservation(observation: Observation): Promise<Directive>;
+    generateAction(directive: Directive): Promise<AgentAction>;
+}
+
+/**
+ * Interface for Agent operations
+ */
+interface IAgent {
+    process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
+    getState(): AgentState;
+    setState(newState: AgentState): void;
+    export(): Soul;
+}
+/**
+ * Pure function to create initial agent state
+ */
+declare const createInitialState: (partial?: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to update agent state
+ * Returns new state without mutating original
+ */
+declare const updateAgentState: (currentState: AgentState, updates: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to process input and generate response
+ */
+declare const processAgentInput: (currentState: AgentState, input: string, context?: Record<string, unknown>) => AgentResponse;
+/**
+ * Pure function to export agent to Soul
+ */
+declare const exportToSoul: (agentId: string, name: string, persona: string, state: AgentState, memories: MemoryItem[]) => Soul;
+/**
+ * Factory function to create Agent
+ */
+declare const createAgent: (config: AgentConfig) => IAgent;
+/**
+ * Pure function to import Agent from Soul
+ */
+declare const fromSoul: (soul: Soul, cortex: ICortex) => IAgent;
+
 /**
  * ForbocAI SDK
  * The Infrastructure Layer for Autonomous AI Characters
+ *
+ * Functional Programming Principles:
+ * - Pure functions with deterministic outputs
+ * - Immutability - state never mutated directly
+ * - No side effects in core logic
+ * - Factory pattern for object creation
  */
 
 declare const init: () => void;
 
-export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type CompletionOptions, type Cortex, type CortexConfig, type CortexStatus, type MemoryConfig, type MemoryItem, type MemoryType, type Mood, type Soul, init };
+export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type CompletionOptions, type CortexConfig, type CortexStatus, type Directive, type IAgent, type ICortex, type MemoryConfig, type MemoryItem, type MemoryType, MockCortex, type Mood, type Observation, type Soul, createAgent, createCortex, createInitialState, exportToSoul, fromSoul, generateActionFromDirective, generateCompletion, init, processAgentInput, processObservationToDirective, updateAgentState };

package/dist/index.d.ts

@@ -9,6 +9,9 @@ interface CortexConfig {
     temperature?: number;
     maxTokens?: number;
     gpu?: boolean;
+    /** Connection Config */
+    authKey?: string;
+    apiUrl?: string;
 }
 interface CortexStatus {
     id: string;
@@ -22,12 +25,6 @@ interface CompletionOptions {
     stop?: string[];
     jsonSchema?: object;
 }
-interface Cortex {
-    id: string;
-    init(): Promise<void>;
-    complete(prompt: string, options?: CompletionOptions): Promise<string>;
-    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
-}
 type Mood = 'hostile' | 'suspicious' | 'neutral' | 'friendly' | 'loyal';
 interface AgentState {
     inventory: string[];
@@ -37,22 +34,17 @@ interface AgentState {
     [key: string]: unknown;
 }
 interface AgentConfig {
-    cortex: Cortex;
+    cortex: any;
     persona: string;
     initialState?: Partial<AgentState>;
     memoryConfig?: MemoryConfig;
+    apiUrl?: string;
 }
 interface AgentResponse {
     dialogue: string;
     action?: AgentAction;
     thought?: string;
 }
-interface AgentAction {
-    type: string;
-    target?: string;
-    payload?: Record<string, unknown>;
-    reason?: string;
-}
 type MemoryType = 'observation' | 'experience' | 'knowledge' | 'emotion';
 interface MemoryConfig {
     /** Decay strategy: 'none' | 'temporal' */
@@ -68,6 +60,28 @@ interface MemoryItem {
     type: MemoryType;
     importance: number;
 }
+interface Observation {
+    type: 'event' | 'state' | 'request';
+    timestamp: number;
+    agentId?: string;
+    gameId?: string;
+    data: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+interface Directive {
+    type: 'system-prompt' | 'action-constraints' | 'behavior-rules';
+    content: string;
+    constraints?: Record<string, unknown>;
+    priority?: 'high' | 'normal' | 'low';
+    expiresAt?: number;
+}
+interface AgentAction {
+    type: string;
+    target?: string;
+    payload?: Record<string, unknown>;
+    reason?: string;
+    confidence?: number;
+}
 interface Soul {
     id: string;
     version: string;
@@ -78,11 +92,90 @@ interface Soul {
     signature?: string;
 }
 
+/**
+ * Interface for Cortex inference engine
+ */
+interface ICortex {
+    init(): Promise<CortexStatus>;
+    complete(prompt: string, options?: CompletionOptions): Promise<string>;
+    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
+    processObservation(observation: Observation): Promise<Directive>;
+    generateAction(directive: Directive): Promise<AgentAction>;
+}
+/**
+ * Cortex factory function - creates a new Cortex instance
+ */
+declare const createCortex: (config: CortexConfig) => ICortex;
+/**
+ * Pure function to generate completion text
+ * Deterministic output for same input (functional principle)
+ */
+declare const generateCompletion: (prompt: string, options: CompletionOptions, modelId: string) => string;
+/**
+ * Pure function to process observation and return directive
+ */
+declare const processObservationToDirective: (observation: Observation) => Directive;
+/**
+ * Pure function to generate action from directive
+ */
+declare const generateActionFromDirective: (directive: Directive) => AgentAction;
+/**
+ * Mock Cortex for testing
+ */
+declare class MockCortex implements ICortex {
+    init(): Promise<CortexStatus>;
+    complete(prompt: string): Promise<string>;
+    completeStream(prompt: string): AsyncGenerator<string>;
+    processObservation(observation: Observation): Promise<Directive>;
+    generateAction(directive: Directive): Promise<AgentAction>;
+}
+
+/**
+ * Interface for Agent operations
+ */
+interface IAgent {
+    process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
+    getState(): AgentState;
+    setState(newState: AgentState): void;
+    export(): Soul;
+}
+/**
+ * Pure function to create initial agent state
+ */
+declare const createInitialState: (partial?: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to update agent state
+ * Returns new state without mutating original
+ */
+declare const updateAgentState: (currentState: AgentState, updates: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to process input and generate response
+ */
+declare const processAgentInput: (currentState: AgentState, input: string, context?: Record<string, unknown>) => AgentResponse;
+/**
+ * Pure function to export agent to Soul
+ */
+declare const exportToSoul: (agentId: string, name: string, persona: string, state: AgentState, memories: MemoryItem[]) => Soul;
+/**
+ * Factory function to create Agent
+ */
+declare const createAgent: (config: AgentConfig) => IAgent;
+/**
+ * Pure function to import Agent from Soul
+ */
+declare const fromSoul: (soul: Soul, cortex: ICortex) => IAgent;
+
 /**
  * ForbocAI SDK
  * The Infrastructure Layer for Autonomous AI Characters
+ *
+ * Functional Programming Principles:
+ * - Pure functions with deterministic outputs
+ * - Immutability - state never mutated directly
+ * - No side effects in core logic
+ * - Factory pattern for object creation
  */
 
 declare const init: () => void;
 
-export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type CompletionOptions, type Cortex, type CortexConfig, type CortexStatus, type MemoryConfig, type MemoryItem, type MemoryType, type Mood, type Soul, init };
+export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type CompletionOptions, type CortexConfig, type CortexStatus, type Directive, type IAgent, type ICortex, type MemoryConfig, type MemoryItem, type MemoryType, MockCortex, type Mood, type Observation, type Soul, createAgent, createCortex, createInitialState, exportToSoul, fromSoul, generateActionFromDirective, generateCompletion, init, processAgentInput, processObservationToDirective, updateAgentState };

package/dist/index.js

@@ -20,9 +20,257 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  init: () => init
+  MockCortex: () => MockCortex,
+  createAgent: () => createAgent,
+  createCortex: () => createCortex,
+  createInitialState: () => createInitialState,
+  exportToSoul: () => exportToSoul,
+  fromSoul: () => fromSoul,
+  generateActionFromDirective: () => generateActionFromDirective,
+  generateCompletion: () => generateCompletion,
+  init: () => init,
+  processAgentInput: () => processAgentInput,
+  processObservationToDirective: () => processObservationToDirective,
+  updateAgentState: () => updateAgentState
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/cortex.ts
+var createCortex = (config) => {
+  return new WebLLMCortex(config);
+};
+var generateCompletion = (prompt, options, modelId) => {
+  const baseResponse = `Response to: ${prompt}`;
+  const temperature = options.temperature ?? 0.7;
+  const maxTokens = options.maxTokens ?? 1024;
+  return baseResponse;
+};
+var processObservationToDirective = (observation) => {
+  return {
+    type: "system-prompt",
+    content: "You are an autonomous agent in a game world. Process the observation and generate appropriate actions.",
+    priority: "normal"
+  };
+};
+var generateActionFromDirective = (directive) => {
+  return {
+    type: "idle",
+    reason: directive.content ?? "No specific directive provided"
+  };
+};
+var WebLLMCortex = class {
+  constructor(config) {
+    this.status = null;
+    this.config = {
+      ...config,
+      temperature: config.temperature ?? 0.7,
+      maxTokens: config.maxTokens ?? 1024,
+      gpu: config.gpu ?? true
+    };
+  }
+  async init() {
+    if (this.status?.ready) {
+      return this.status;
+    }
+    const apiUrl = this.config.apiUrl || "http://localhost:8080";
+    try {
+      const response = await fetch(`${apiUrl}/cortex/init`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          requestedModel: this.config.model,
+          authKey: this.config.authKey
+          // Send the key!
+        })
+      });
+      if (!response.ok) {
+        console.warn("Cortex Authorization Failed:", response.statusText);
+        throw new Error("Authorization Failed");
+      }
+      const data = await response.json();
+      const newStatus = {
+        id: data.cortexId,
+        model: this.config.model,
+        ready: true,
+        engine: "webballm"
+      };
+      this.status = newStatus;
+      return newStatus;
+    } catch (e) {
+      console.warn("Failed to connect to Neural Grid. Falling back to offline mode.");
+      const newStatus = {
+        id: "offline-" + Math.random().toString(36).substring(7),
+        model: this.config.model,
+        ready: true,
+        engine: "mock"
+      };
+      this.status = newStatus;
+      return newStatus;
+    }
+  }
+  async complete(prompt, options = {}) {
+    if (!this.status?.ready) {
+      throw new Error("Cortex not initialized");
+    }
+    const result = generateCompletion(prompt, options, this.config.model);
+    return result;
+  }
+  async *completeStream(prompt, options = {}) {
+    const result = await this.complete(prompt, options);
+    for (const char of result) {
+      yield char;
+    }
+  }
+  async processObservation(observation) {
+    return processObservationToDirective(observation);
+  }
+  async generateAction(directive) {
+    return generateActionFromDirective(directive);
+  }
+};
+var MockCortex = class {
+  async init() {
+    return {
+      id: "mock-cortex",
+      model: "mock-model",
+      ready: true,
+      engine: "mock"
+    };
+  }
+  async complete(prompt) {
+    return generateCompletion(prompt, {}, "mock-model");
+  }
+  async *completeStream(prompt) {
+    yield `Mock streaming response to: ${prompt}`;
+  }
+  async processObservation(observation) {
+    return {
+      type: "system-prompt",
+      content: "Mock processing of observation"
+    };
+  }
+  async generateAction(directive) {
+    return {
+      type: "mock-action",
+      reason: "Mock action generation"
+    };
+  }
+};
+
+// src/agent.ts
+var createInitialState = (partial) => {
+  return {
+    inventory: partial?.inventory ?? [],
+    skills: partial?.skills ?? {},
+    relationships: partial?.relationships ?? {},
+    mood: partial?.mood ?? "neutral"
+  };
+};
+var updateAgentState = (currentState, updates) => {
+  return {
+    ...currentState,
+    ...updates,
+    // Preserve nested immutability
+    inventory: updates.inventory !== void 0 ? [...updates.inventory] : [...currentState.inventory],
+    skills: { ...currentState.skills, ...updates.skills || {} },
+    relationships: { ...currentState.relationships, ...updates.relationships || {} }
+  };
+};
+var processAgentInput = (currentState, input, context = {}) => {
+  return {
+    dialogue: `Processing: "${input}" (Mood: ${currentState.mood})`,
+    action: {
+      type: "respond",
+      reason: "Default processing"
+    }
+  };
+};
+var exportToSoul = (agentId, name, persona, state, memories) => {
+  return {
+    id: agentId,
+    version: "1.0.0",
+    name,
+    persona,
+    memories: [...memories],
+    // Copy array for immutability
+    state: { ...state }
+    // Copy state for immutability
+  };
+};
+var createAgent = (config) => {
+  return new AgentImpl(config);
+};
+var AgentImpl = class {
+  constructor(config) {
+    this.config = config;
+    this.cortex = config.cortex;
+    this.state = createInitialState(config.initialState);
+    this.memories = [];
+  }
+  async process(input, context = {}) {
+    const currentState = this.getState();
+    const hp = currentState.hp || 100;
+    const apiUrl = this.config.apiUrl || "http://localhost:8080";
+    const apiContext = Object.entries(context).map(([k, v]) => [k, String(v)]);
+    apiContext.push(["hp", String(hp)]);
+    let directive = "Respond normally.";
+    let instruction = "IDLE";
+    try {
+      const apiResponse = await fetch(`${apiUrl}/agents/mock-agent-id/process`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          input,
+          context: apiContext
+        })
+      });
+      if (apiResponse.ok) {
+        const data = await apiResponse.json();
+        directive = data.directive;
+        instruction = data.instruction;
+      } else {
+        console.warn("API Error, falling back to local.");
+      }
+    } catch (e) {
+      console.warn("API Unreachable, falling back to local.", e);
+    }
+    const prompt = `${directive}
+
+User: ${input}
+Agent:`;
+    const generatedText = await this.cortex.complete(prompt);
+    return {
+      dialogue: generatedText,
+      action: { type: instruction, reason: directive },
+      thought: `Directive: ${directive}`
+    };
+  }
+  getState() {
+    return { ...this.state };
+  }
+  setState(newState) {
+    this.state = newState;
+  }
+  export() {
+    return exportToSoul(
+      "agent-" + Math.random().toString(36).substring(7),
+      "Agent",
+      this.config.persona,
+      this.state,
+      this.memories
+    );
+  }
+};
+var fromSoul = (soul, cortex) => {
+  const agent = createAgent({
+    cortex,
+    persona: soul.persona,
+    initialState: soul.state
+  });
+  return agent;
+};
+
+// src/index.ts
 var init = () => {
   const reset = "\x1B[0m";
   const cyan = "\x1B[36m";
@@ -45,5 +293,16 @@ ${cyan}Welcome to the Future of NPC Intelligence.${reset}
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  init
+  MockCortex,
+  createAgent,
+  createCortex,
+  createInitialState,
+  exportToSoul,
+  fromSoul,
+  generateActionFromDirective,
+  generateCompletion,
+  init,
+  processAgentInput,
+  processObservationToDirective,
+  updateAgentState
 });

package/dist/index.mjs

@@ -1,3 +1,238 @@
+// src/cortex.ts
+var createCortex = (config) => {
+  return new WebLLMCortex(config);
+};
+var generateCompletion = (prompt, options, modelId) => {
+  const baseResponse = `Response to: ${prompt}`;
+  const temperature = options.temperature ?? 0.7;
+  const maxTokens = options.maxTokens ?? 1024;
+  return baseResponse;
+};
+var processObservationToDirective = (observation) => {
+  return {
+    type: "system-prompt",
+    content: "You are an autonomous agent in a game world. Process the observation and generate appropriate actions.",
+    priority: "normal"
+  };
+};
+var generateActionFromDirective = (directive) => {
+  return {
+    type: "idle",
+    reason: directive.content ?? "No specific directive provided"
+  };
+};
+var WebLLMCortex = class {
+  constructor(config) {
+    this.status = null;
+    this.config = {
+      ...config,
+      temperature: config.temperature ?? 0.7,
+      maxTokens: config.maxTokens ?? 1024,
+      gpu: config.gpu ?? true
+    };
+  }
+  async init() {
+    if (this.status?.ready) {
+      return this.status;
+    }
+    const apiUrl = this.config.apiUrl || "http://localhost:8080";
+    try {
+      const response = await fetch(`${apiUrl}/cortex/init`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          requestedModel: this.config.model,
+          authKey: this.config.authKey
+          // Send the key!
+        })
+      });
+      if (!response.ok) {
+        console.warn("Cortex Authorization Failed:", response.statusText);
+        throw new Error("Authorization Failed");
+      }
+      const data = await response.json();
+      const newStatus = {
+        id: data.cortexId,
+        model: this.config.model,
+        ready: true,
+        engine: "webballm"
+      };
+      this.status = newStatus;
+      return newStatus;
+    } catch (e) {
+      console.warn("Failed to connect to Neural Grid. Falling back to offline mode.");
+      const newStatus = {
+        id: "offline-" + Math.random().toString(36).substring(7),
+        model: this.config.model,
+        ready: true,
+        engine: "mock"
+      };
+      this.status = newStatus;
+      return newStatus;
+    }
+  }
+  async complete(prompt, options = {}) {
+    if (!this.status?.ready) {
+      throw new Error("Cortex not initialized");
+    }
+    const result = generateCompletion(prompt, options, this.config.model);
+    return result;
+  }
+  async *completeStream(prompt, options = {}) {
+    const result = await this.complete(prompt, options);
+    for (const char of result) {
+      yield char;
+    }
+  }
+  async processObservation(observation) {
+    return processObservationToDirective(observation);
+  }
+  async generateAction(directive) {
+    return generateActionFromDirective(directive);
+  }
+};
+var MockCortex = class {
+  async init() {
+    return {
+      id: "mock-cortex",
+      model: "mock-model",
+      ready: true,
+      engine: "mock"
+    };
+  }
+  async complete(prompt) {
+    return generateCompletion(prompt, {}, "mock-model");
+  }
+  async *completeStream(prompt) {
+    yield `Mock streaming response to: ${prompt}`;
+  }
+  async processObservation(observation) {
+    return {
+      type: "system-prompt",
+      content: "Mock processing of observation"
+    };
+  }
+  async generateAction(directive) {
+    return {
+      type: "mock-action",
+      reason: "Mock action generation"
+    };
+  }
+};
+
+// src/agent.ts
+var createInitialState = (partial) => {
+  return {
+    inventory: partial?.inventory ?? [],
+    skills: partial?.skills ?? {},
+    relationships: partial?.relationships ?? {},
+    mood: partial?.mood ?? "neutral"
+  };
+};
+var updateAgentState = (currentState, updates) => {
+  return {
+    ...currentState,
+    ...updates,
+    // Preserve nested immutability
+    inventory: updates.inventory !== void 0 ? [...updates.inventory] : [...currentState.inventory],
+    skills: { ...currentState.skills, ...updates.skills || {} },
+    relationships: { ...currentState.relationships, ...updates.relationships || {} }
+  };
+};
+var processAgentInput = (currentState, input, context = {}) => {
+  return {
+    dialogue: `Processing: "${input}" (Mood: ${currentState.mood})`,
+    action: {
+      type: "respond",
+      reason: "Default processing"
+    }
+  };
+};
+var exportToSoul = (agentId, name, persona, state, memories) => {
+  return {
+    id: agentId,
+    version: "1.0.0",
+    name,
+    persona,
+    memories: [...memories],
+    // Copy array for immutability
+    state: { ...state }
+    // Copy state for immutability
+  };
+};
+var createAgent = (config) => {
+  return new AgentImpl(config);
+};
+var AgentImpl = class {
+  constructor(config) {
+    this.config = config;
+    this.cortex = config.cortex;
+    this.state = createInitialState(config.initialState);
+    this.memories = [];
+  }
+  async process(input, context = {}) {
+    const currentState = this.getState();
+    const hp = currentState.hp || 100;
+    const apiUrl = this.config.apiUrl || "http://localhost:8080";
+    const apiContext = Object.entries(context).map(([k, v]) => [k, String(v)]);
+    apiContext.push(["hp", String(hp)]);
+    let directive = "Respond normally.";
+    let instruction = "IDLE";
+    try {
+      const apiResponse = await fetch(`${apiUrl}/agents/mock-agent-id/process`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          input,
+          context: apiContext
+        })
+      });
+      if (apiResponse.ok) {
+        const data = await apiResponse.json();
+        directive = data.directive;
+        instruction = data.instruction;
+      } else {
+        console.warn("API Error, falling back to local.");
+      }
+    } catch (e) {
+      console.warn("API Unreachable, falling back to local.", e);
+    }
+    const prompt = `${directive}
+
+User: ${input}
+Agent:`;
+    const generatedText = await this.cortex.complete(prompt);
+    return {
+      dialogue: generatedText,
+      action: { type: instruction, reason: directive },
+      thought: `Directive: ${directive}`
+    };
+  }
+  getState() {
+    return { ...this.state };
+  }
+  setState(newState) {
+    this.state = newState;
+  }
+  export() {
+    return exportToSoul(
+      "agent-" + Math.random().toString(36).substring(7),
+      "Agent",
+      this.config.persona,
+      this.state,
+      this.memories
+    );
+  }
+};
+var fromSoul = (soul, cortex) => {
+  const agent = createAgent({
+    cortex,
+    persona: soul.persona,
+    initialState: soul.state
+  });
+  return agent;
+};
+
 // src/index.ts
 var init = () => {
   const reset = "\x1B[0m";
@@ -20,5 +255,16 @@ ${cyan}Welcome to the Future of NPC Intelligence.${reset}
 `);
 };
 export {
-  init
+  MockCortex,
+  createAgent,
+  createCortex,
+  createInitialState,
+  exportToSoul,
+  fromSoul,
+  generateActionFromDirective,
+  generateCompletion,
+  init,
+  processAgentInput,
+  processObservationToDirective,
+  updateAgentState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "forbocai",
-    "version": "0.0.7",
+    "version": "0.0.8",
     "description": "The Infrastructure Layer for Autonomous AI Characters",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -11,12 +11,20 @@
     "scripts": {
         "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
         "dev": "tsup src/index.ts --watch",
-        "test": "echo 'No tests yet'",
+        "test": "vitest",
+        "test:watch": "vitest --watch",
         "postinstall": "node postinstall.js"
     },
+    "dependencies": {
+        "@mlc-ai/web-llm": "^0.2.0",
+        "zod": "^3.22.4",
+        "axios": "^1.6.2"
+    },
     "devDependencies": {
-        "tsup": "^8.0.0",
-        "typescript": "^5.0.0"
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3",
+        "vitest": "^1.0.0",
+        "@types/node": "^20.0.0"
     },
     "files": [
         "dist",
@@ -24,4 +32,4 @@
         "package.json",
         "postinstall.js"
     ]
-}
+}